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PREFACE 



The TOPS-20 Monitor Calls User's Guide is written for the assembly 
language user who is unfamiliar with the DECSYSTEM-20 monitor calls. 
The manual introduces the user to the functions that he can request of 
the monitor from within his assembly language programs. The manual 
also teaches him how to use the basic monitor calls for performing 
these functions. 

This manual is not a reference document, nor is it complete 
documentation of the entire set of monitor calls. It is organized 
according to functions, starting with the simple and proceeding to the 
more advanced. 

Each chapter should be read from beginning to end. A user who skips 
around in his reading will not gain the full benefit of this manual. 
Once the user has a working knowledge of the monitor calls in this 
document, he should then refer to the TOPS-20 Moni tor Cal Is Reference 
Manual for the complete descriptions of all the calls. 

To understand the examples in this manual, the user must be familiar 
with the MACRO language and the DECSYSTEM-20 machine instructions. 
The TOPS-20 MACRO Assembler Reference Manual documents the MACRO 
language. The TOPS-20 LINK Reference Manual describes the linking 
loader. The DECsystem- 10/DECSYSTEM-20 Processor Reference Manual 
contains the information on the machine instructions. These three 
manuals should be used together with the Monitor Calls User's Guide, 
and should be referred to when questions arise on the MACRO language 
or the instruction set. Another useful reference is I ntroduction to 
DECSYSTEM-20 Assembl y Language Programming by Ralph E. Gorin, 
published by the Digital Press. It provides a thorough treatment of 
assembly language programming for the DECSYSTEM-20, emphasizing the 
analysis of programs and various methods of program synthesis. 

In addition, some of the examples in this manual contain macros and 
symbols (MOVX, TMSG, JSERR, or JSHLT, for example) from the MACSYM 
system file. This file is a universal file of definitions available 
to the user as a means of producing consistent and readable programs. 

Finally, the user should be familiar with the TOPS-20 Command Language 

to enter and run the examples. The TOPS-20 User ' s Guide describes the 

| TOPS-20 commands and system programs. The TOPS-20 Commands Reference 

J Manual describes all operating system commands available to the 

j nonpr ivi leged user of TOPS-20. 

ix 



CHAPTER 1 
INTRODUCTION 



1.1 OVERVIEW 

A program written in MACRO assembly language consists of a series of 
statements, each statement usually corresponding to one or more 
machine language instructions. Each statement in the MACRO program 
may be one of the following types: 

1. A MACRO assembler directive, or pseudo-operation (pseudo-op), 
such as SEARCH or END. These pseudo-ops are commands to the 
MACRO assembler and are performed when the program is 
assembled. Refer to the DECSYSTEM-20 MACRO Assembler 
Reference Manual for detailed descriptions of the MACRO 
pseudo-ops . 

2. A MACRO assembler direct assignment statement. These 
statements are in the form 

symbol =value 

and are used to assign a specific value to a symbol. 
Assignment statements are processed by the MACRO assembler 
when the program is assembled. These statements do not 
generate instructions or data in the assembled program. 

3. A MACRO assembler constant declaration statement, such as 
ONE: EXP 1 

These statements are processed when the program is assembled. 

k. An instruction mnemonic, or symbolic instruction code, such 
as MOVE or ADD. These symbolic instruction codes represent 
the operations performed by the central processor when the 
program is executed. Refer to the DECsystem-10/DECSYSTEM-20 
Processor Reference Manual for detailed descriptions of the 
symbolic instruction codes. 
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5. A monitor call, or JSYS, such as RESET or BIN. These calls 
are commands to the monitor and are performed when the 
program is executed. This manual describes the commonly-used 
monitor calls. However, the user should refer to the TOPS-20 
Moni tor Cal 1 s Reference Manual for detailed descriptions of 
al 1 the cal Is. 

When the MACRO program is assembled, the MACRO assembler processes the 
statements in the program by 

• translating symbolic instruction codes to binary codes. 

• relating symbols to numeric values. 

• assigning relocatable or absolute memory addresses. 

The MACRO assembler also converts each symbolic call to the monitor 
into a Jump-to-System (JSYS) instruction. 



1.2 MONITOR CALLS 

Monitor calls are used to request monitor functions, such as input or 
output of data (I/O), error handling, and number conversions, during 
the execution of the program. These calls are accomplished with the 
JSYS instruction (operation code 10*t) , where the address portion of 
the instruction indicates the particular function. 

Each monitor call has a predefined symbol indicating the particular 
monitor function to be performed (for example, 0PENF% to indicate 
opening a file). The symbols are defined in a system file called 
MONSYM. Monitor calls defined in Release k and later require a 
percent sign (%) as the final character in the call symbol. Monitor 
calls defined prior to Release k do not require the %, but do accept 
it. The current convention is that all monitor calls use the % as 
part of the call symbol. This manual follows that convention. To use 
the symbols and to cause them to be defined correctly, the user's 
program must contain the statement 

SEARCH MONSYM 

at the beginning of the program. During the assembly of the program, 
the assembler replaces the monitor call symbol with an instruction 
containing the operation code 10k in the left half and the appropriate 
function code in the right half. 

Arguments for a JSYS instruction are placed in accumulators (ACs) . 
Any data resulting from the execution of the JSYS instruction are 
returned in the accumulators or in an address in memory to which an 
accumulator points. Therefore, before the JSYS instruction can be 
executed, the appropriate arguments must be placed in the specific 
accumulators. 
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The system file MACSYM. MAC contains a number of useful macros for the 
assembly language programmer. To use MACSYM macros, the user's 
program must contain the statements 

SEARCH MACSYM 

•REQUIRE SYS:MACREL {include support routines 

at the beginning of the program. Since most bits defined for use with 
the monitor have symbolic names, macros enable the programmer to 
utilize these bits without knowledge of their exact position. Several 
MACSYM macros that are especially valuable to the TOPS-20 assembly 
language programmer are MOVX, TXnn (where nn indicates one of the 6k 
test instructions provided by the hardware), and FLD. MOVX loads an 
AC with a constant using the proper MOVE instructions, depending on 
the constant's position in the word. The TXnn macros expand to allow 
all combinations of modification and testing to be defined. For 
example 

TXNN ACl.GSfcEOF 

tests AC1 for the presence of GS%E0F, no modification, and skip if not 
equal to zero. This instruction will work regardless of the actual 
bit position of GS%E0F . The FLD macro causes a value to be right 
justified in a field. For example 

FLD(7,0F%BSZ) 

places the value 7 in position 0F%BSZ, right justified at bit 5 
(0F%BSZ is defined as bits 0-5). These macros will be used 
consistently throughout this document. 



1.2.1 Calling Sequence 

Arguments for the calls are placed in accumulators 1 through k 
(AC1-AC4) . If more than four arguments are required for a particular 
call, the arguments are placed in a list to which an accumulator 
points. The arguments for the calls are specific bit settings or 
values. These bit settings and values are defined in MONSYM with 
symbol names, which can be used in the program. In fact, it is 
recommended that the user write his program using symbols whenever 
possible. This makes the program easier to read by another user. Use 
of symbols also allows the values of the symbols to be redefined 
without requiring the program to be changed. In this manual, the 
arguments for the monitor calls are described with both the bit 
settings and the symbol names. All program examples are written using 
the symbol names. 

The set of instructions that place the arguments in the accumulators 
is followed by one line of code giving the particular monitor call 
symbol. During the program's execution, control is transferred to the 
monitor when this line of code is reached. 
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1.2.2 Error Returns 

TOPS-20 provides a consistent way to handle all JSYS errors. For most 
monitor calls upon a successful return, the instruction following the 
call is executed. If an error occurs during the execution of the 
call, the monitor examines the instruction following the call. If the 
instruction is a JUMP instruction with the AC field specified as 
12-17. the monitor transfers control to a user-specified address. If 
the instruction is not a JUMP instruction, the monitor generates an 
illegal instruction trap indicating an illegal instruction, which the 
user's program can process via the software interrupt system (refer to 
Chapter k) . If the user's program is not prepared to process the 
instruction trap, the program execution halts, and a message is output 
stating the reason for failure. 

To place a JUMP instruction in his program, the user can include a 
statement using one of six predefined symbols. These symbols are 

ERJMPR address (= JUMP 12, address) 

ERCALR address (= JUMP 13, address) 

ERJMPS address (= JUMP 14, address) 

ERCALS address (= JUMP 15, address) 

ERJMP address (= JUMP 16, address) 

ERCAL address (= JUMP 17, address) 

and cause the assembler to generate a JUMP instruction. The JUMP 
instruction is a non-operation instruction (that is, a no-op) as far 
as the hardware is concerned. However, the monitor executes the JUMP 
instruction by transferring control to the address specified, which is 
normally the beginning of an error processing routine written by the 
user. If the user includes the ERJMP symbol, control is transferred 
as though a JUMPA instruction had been executed, and control does not 
return to his program after the error routine is finished. If the 
user includes the ERCAL symbol, control is transferred as though a 
PUSHJ 17, address instruction had been executed. If the error routine 
executes a POPJ 17, instruction, control returns to the user's program 
at the location following the ERCAL. 

If the user includes the ERJMPR symbol, the monitor behaves the same 
as it would if the ERJMP symbol had been included, except that the 
last error encountered by the process is stored in the user's AC1. 
(Refer to Appendix B of the TOPS-20 Monitor Cal Is Reference Manual for 
the list of error codes, mnemonics, and message strings.) The ERCALR 
symbol functions the same as ERCAL except the error code encountered 
is returned in the user's AC1 . ERJMPS and ERCALS function similarly 
except the monitor suppresses the storing of the error code in the 
user|s AC1. Instead, AC1 is preserved and contains either the 
original contents from when the monitor call was given, or a partially 
updated value prior to the error. 
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Prior to the implementation of the ERJMP/ERCAL facilities, certain 
monitor calls returned control to the user's program at various 
locations after the calling address. Approximately one third of the 
JSYSs return to the +1 address only on failure, and to the location 
immediately following that (the +2 address) on successful execution of 
the call. A few calls return +1 , +2, or +3, dependent on varying 
conditions of success or failure (for examples, see ERSTR% or GACTF% 
in the TOPS-20 Monitor Cal Is Reference Manual ) ; and some cal Is do not 
return at all (see HALTF% or WAIT%) . Refer to Chapter 3 of the 
TOPS-20 Moni tor Cal Is Reference Manual for the possible returns for 
each moni tor cal 1 . 

When a failure occurs during the execution of a monitor call, the 
monitor stores an error code. The error code indicates the cause of 
the failure. This error code is usually stored in the right half of 
AC1, but can also be stored in the monitor's data base or a user's 
data block. In either case, you can obtain the message associated 
with the error by using the GETER% or ERSTR% call. 

The ERJMP/ERCAL facilities can also be used following a machine 
instruction, and will trap for the following conditions: 

• I 1 legal instruction 

• Illegal memory read 

• Illegal memory write 

• Pushdown list overflow 

The ERJMP/ERCAL facilities can be used after all monitor calls, 
regardless of whether the call has one or two returns. To handle 
errors consistently, users are encouraged to employ either the ERJMPR, 
ERCALR, ERJMPS, or ERCALS symbol with all calls. All of the six 
predefined jump symbols are no-ops, unless they immediately follow a 
monitor call or instruction that fails. Error codes can be obtained 
by the program and translated into their corresponding error mnemonic 
and message strings with the GETER% and ERSTR% monitor calls. 

TOPS-20 provides convenient macros and subroutines for handling 
monitor call error routines. They can be found in the system file 
MACSYM.MAC. Two such macros are EJSERR and EJSHLT. EJSERR prints out 
an error message and returns control to the next instruction following 
the failing monitor call. EJSHLT prints out an error message and 
halts processing of the program. 
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The following is an example of executing the B 1 N% monitor call (see 
Chapter 3 for more information on this monitor call) that has a single 
return. If the execution of the call is successful, the program reads 
and stores a character. If the execution of the call is not 
successful, the program transfers control to an error routine. This 
routine processes the error and then returns control back to the main 
program sequence. Note that ERCALS stores the return address on the 
stack. 



DOIT: MOVE T1.INJFN 
BIN% 

ERCALS ERROR 
MOVEM T2.CHAR 



JRST 
ERROR: GTSTS% 
TXNE 
JRST 
HRROI 
? INPUT ERROR, 
/] 

PS0UT% 
RET 



DOIT 

T2,GS%E0F 
EOF 

T1,[ASCIZ/ 
CONTINUING 

;no, 



jobtain JFN for input file 

; input one character 

;call error routine if problem 

;store character 

;and get another 

;read file status 

;end of file? 

;yes, process end-of-file condition 



data error 
;pr i nt message 
;return to program (POPJ 17») 



| The ASCIZ pesudo-op specifies a left-justified ASCII string terminated 
j with a null (that is, a byte containing all bits equal to zero) byte. 



1.3 PROGRAM ENVIRONMENT 

The user program environment in the TOPS-20 operating system consists 
of a job structure that can contain many processes. A process is a 
runnable or schedulable entity capable of performing computations in 
parallel with other processes. This means that a runnable program is 
associated with at least one process. 

Each process has i ts own address space for storing its computations. 
This address space is called virtual space because it is actually a 
"window" into physical storage. The address space is divided into 32 
(decimal) sections. Each section is divided into 512 (decimal) pages, 
and each page contains 512 (decimal) words. Each word contains 36 
bi ts. 

A process can communicate with other processes in the following ways: 

• explicitly, by software interrupts or system facilities (the 
inter-process communication facility, or IPCF, for example). 

• implicitly, by changing parts of its environment (its address 
space, for instance) that are being shared with other 
processes . 
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A process can create other processes inferior to it, but there is one 
control process from which the chain of creations begins. A process 
is said to exist when a superior process creates it and is said to end 
when a superior process deletes it. Refer to Chapter 5 for more 
information on the process structure. 

A set of one or more related processes, normally under control of a 
single user, is a job. Each active process is part of some job on the 
system. A job is defined by a user name, an account number, some open 
files, and a set of running and/or suspended processes. A job can be 
composed of several running or suspended programs. 

The following diagram illustrates a job structure consisting of four 
processes. 



\ 



/ 



/ 



TOP PROCESS 




Job 



Process A 



Process B 



\ 



Process C 



/ 



/ 



/ 



MR-S-2037-82 



| Both process A and 1 process B are created by the TOP PROCESS and thus 

j are directly inferior to it. Process C is created by process B and 

j thus is directly inferior to process B only. Process C is indirectly 

| inferior to the TOP PROCESS. 

| In summary, processes can be considered as independent virtual jobs 
with well-defined relationships to other processes in the system, and 
a job is a collection of these processes. 
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CHAPTER 2 
INPUT AND OUTPUT USING THE TERMINAL 



One of the main reasons for using monitor calls is to transfer data 
from one location to another. This chapter discusses moving data to 
and from the user's terminal. 



2.1 OVERVIEW 

Data transfers to and from the terminal are in the form of either 
individual bytes or text strings. The bytes are 7-bit bytes. The 
strings are ASCII strings ending with a byte. These strings are 
cal led ASCIZ strings. 

To designate the desired string, the user's program must include a 
statement that points to the beginning of the string being read or 
written. The MACRO pseudo-op, POINT, can be used to set up this 
pointer, as shown in the following sequence of statements: 

MOVE AC1.PTR 



PTR: POINT 7, MSG 

MSG: ASCIZ/TEXT MESSAGE/ 

Accumulator 1 contains the symbolic address (PTR) of the pointer. At 
the address specified by PTR is the pointer to the beginning of the 
string. The pointer is set up by the POINT pseudo-op. The general 
format of the POINT pseudo-op is: 

POINT decimal -byte- si ze,address,decimal-byte-pos i t ion 

(Refer to the TOPS-20 MACRO Assembler Reference Manual for more 
information on the POINT pseudo-op.) In the example above, the POINT 
pseudo-op has been written to indicate 7-bit bytes starting before the 
left-most bit in the address specified by MSG. 
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Another way of setting up an accumulator to contain the address of the 
pointer is with the following statement: 

HRROI AC1, [ASCI Z/TEXT MESSAGE/] 

The instruction mnemonic HRROI causes a -1 to be placed in the left 
half of accumulator 1 and the address of the string to be placed in 
the right half. However, in the above statement, a literal (enclosed 
in square brackets) has been used instead of a symbolic address. The 
literal causes the MACRO assembler to: 

• store data within brackets (the string) in a table. 

• assign an address to the first word of the data. 

• insert that address as the operand to the HRROI instruction. 

Literals have the advantage of showing the data at the point in the 
program where it will be used, instead of showing it at the end of the 
program. 

As far as the I/O monitor calls are concerned, a word in this format 
(-1 in the left half and an address in the right half) designates the 
system's standard pointer (that is, a pointer to a 7 _ bit ASCIZ string 
beginning before the leftmost byte of the string). The result of the 
HRROI statement is interpreted by the monitor as functionally 
equivalent to the word assembled by the POINT 7» address pseudo-op and 
is the recommended statement to use in preparation for a monitor call. 
However, byte manipulation instructions (for example, ILDB, IBP, 
ADJBP) will not operate properly with this type of pointer. 

After a string is read, the pointer is advanced to the character 

following the terminating character of the string. After a string is 

written, the pointer is advanced to the character following the last 
non-null character written. 

Most TOPS-20 monitor calls accept one-word global byte pointers when 
executed from a nonzero section (see Section 8.3) • Global byte 
pointers are used with extended addressing and are fully explained in 
Chapter 8 of this document. Unless specifically stated, TOPS-20 
monitor calls do not accept two-word global byte pointers. 
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2.2 PRIMARY I/O DESIGNATORS 

To transfer data from one location to another, the user's program must 
indicate the source from which the data is to be obtained and the 
destination where the data is to be placed. By default, the user's 
terminal is defined as the source and destination. The default can be 
overridden by using the SPJFN% monitor call (refer to the TOPS-20 
Moni | :or £ills Reference Manual ) . Examples in this book assume the 
user's terminal to be the source (input) and destination (output) 
device. Two designators are used to represent the user's terminal: 



1. The symbol . PR I IN to represent the user's terminal as 
source (input) device. 



the 



2. The symbol .PRIOU to represent the user's terminal as the 
destination (output) device. 

These symbols are called the primary input and output designators and 
by default are used to represent the terminal running the program. 
They are defined in the system file MONSYM.MAC and do not have to be 
defined in the user's program as long as the program contains the 
statement 

SEARCH MONSYM 



2.3 PRINTING A STRING 

Many times a program may need to print an error message or some other 

string, such as a prompt to request input from the user at the 

terminal. The PS0UT% (Primary String Output) monitor call is used to 
print such a string on the terminal. This call copies the designated 

string from the program's address space. Thus, the source of the data 

is the program's address space, and the destination for the data is 

the terminal. The program need only supply the pointer to the string 
being printed. 

Accumulator 1 (AC1) is used to contain the address of the pointer. 
After AC1 is set up with the pointer to the string, the next line of 
code is the PS0UT% call. Thus, an example of the PS0UT% call is: 

HRROI AC1,[ASCIZ/TEXT MESSAGE/] ;string to print 
PS0UT% ; print TEXT MESSAGE 
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The PSOUT% call prints on the terminal all the characters in the 
string until it encounters a null byte. Note that the string is 
printed exactly as it is stored in the program, starting at the 
current position of the terminal's print head or cursor and ending 
with the last character in the string. If a carriage return and line 
feed are to be output, either before or after the string, these 
characters should be inserted as part of the string. For example, to 
print TEXT MESSAGE on one line and to output a carriage return-line 



feed after it, the user's program includes the call 



/] 



HRROI AC1,[ASCIZ/TEXT MESSAGE 
PS0UT% 



After the string is printed, the instruction following the PS0UT% call 

in the user's program is executed. Also, the pointer in AC1 is 

updated to point to the character following the last non-null 
character wr i tten. 

The macro TMSG, found in the system file MACSYM, does the same thing 
as the example above. This macro offers the programmer a convenient 
way for printing messages on the terminal. For example 

TMSG <TEXT MESSAGE 
> 

caused the text message contained between the angle brackets, 
including the carriage return and line feed, to print on the terminal. 
The TMSG macro, along with others previously mentioned, will be used 
consistently in examples throughout this document. Refer to the 
system file MACSYM. MAC for further information on MACSYM macros. 

Refer to Section 1.2.2 for information concerning error returns. 



2.4 READING A NUMBER 

The NIN% (Number Input) monitor call is used to 
call does not assume the terminal as the source 
the user's program must specify this. The N 
number from any valid source designator, includ 
This section discusses reading a number directl 
Refer to Section 2.9 for an example of using th 
number from a string in memory. The destinatio 
AC2, and the NIN% call places the binary value 
this accumulator. The user's program also spec 
that represents the radix of the number being 
can be in the range 2-36. 



read an integer. This 
designator; therefore, 
I N% cal 1 accepts the 
ing a string in memory, 
y from the terminal . 
e NIN% call to read the 
n for the number is 
of the number read into 
ifies a number in AC3 
input. The radix given 
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Thus, the setup for the NIN% monitor call is the following: 

MOVEI AC1..PRIIN ;AC1 contains the primary input designator 

; (the user 's terminal) 



MOVEI AC3.AD10 



NIN$ 



;AC3 contains the radix of the number being 
; input (in this case a decimal number) 

;The call to input the number 



After completion of the N I N% call, control returns to the program at 

one of two places (refer to Section 1.2.2). If an error occurs during 

the execution of the call, control returns to the instruction 

following the call. This instruction should be a jump-type 

| instruction to an error processing routine (see Section 1.2.2). Also, 

[ an error code is placed in AC3 (refer to Appendix B of the TOPS-20 

I Monitor C al Is Reference Manual for the error codes) . If the execution 

of the N I N% call is successful, control returns to the second 

instruction following the call. The number input from the terminal is 

placed in AC2. 

The NIN% call terminates when it encounters a nondigit character (for 
example, a letter, a punctuation character, or a control character). 
This means that if 32X1 were typed on the terminal, on return AC2 
| contains a 40 (octal) because the NIN% call terminated when it read 
the X. 

The following program prints a message and then accepts a decimal 
| number from the user at the terminal. Note that the N I N% call 

terminates reading on any nondigit character; therefore, the user 

cannot edit his input with any of the editing characters (for example, 
| DELETE, CTRL/W) . The RDTTY% cal 1 (refer to Section 2.9) should be 

used in programs that read from the terminal because it allows the 

user to edit his input as he is typing it. 

SEARCH MONSYM 
HRROI AC1.CASCIZ/ 
Enter # of seconds: /] 

PS0UT% ; output a prompt message 

MOVEI AC1,.PRIIN ;input from the terminal 

MOVEI AC3.AD10 ;use the decimal radix 

NIN% ;input a decimal number 

ERJMP NINERR ;error-go to error routine 

MOVEM AC2, NUMSEC ;save number entered 



NUMSEC:BLOCK 1 
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2.5 WRITING A NUMBER 

The NOUT% (Number Output) monitor call is used to output an integer. 
The user's program moves the number to be output into AC2. The 
program must specify the destination for the number in AC1 and the 
radix in which the number is to be output in AC3- The radix given 
cannot be greater than base 36. In addition, the user's program can 
speci f y 
number . 



certain formatting options to be used when printing the 



Thus, the general setup for the N0UT% monitor call is as follows: 

AC1: output designator 

AC2: number being output 

AC3: format options in left half and radix in right half 

The format options that can be specified in the left half of AC3 are 
described in Table 2-1. 
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Table 2-1: NOUT% Format Option 



Bit 



Symbol 



Meani ng 



N0%MAG Print the number as a positive 36-bit 
number. For example, -1 would be printed 
as 777777 777777 if radix=8) . 

N0%SGN Print the appropriate sign (+ or -) before 
the number. If bits N0%MAG and N0%SGN are 
both on, a plus sign is always printed. 



N0%LFL 



Print leadi ng f i 1 ler . 
set, trai 1 i ng f i 1 ler 
N0%ZR0 is ignored. 



If this bit is not 
is printed and bit 



N0%ZR0 



I * 



N0%00V 



N0%AST 



Use O's as the leading filler if the 
specified number of columns allows filling. 
If this bit is not set, blanks are used as 
the leading filler if the number of columns 
a 1 1 ows f i 1 1 i ng . 

Output on column overflow and return an 
error. If this bit is not set, column 
overflow is not output. 

Print asterisks when the column overflows. 
If this bit is not set, and bit k (N0%00V) 
is set, all necessary digits are printed 
when the columns overflow. 



6-10 
11-17 



N0%C0L 



Reserved for Digital (must be 0). 

Print the number of columns indicated. 
This value includes the sign column. If 
this field is 0, as many columns as 
necessary are printed. 
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The following instruction sequence is an example of the N0UT% monitor 
call. This sequence prints a number, stored in location NUMB, on the 
user's terminal. The number can be positive, negative or zero, with 
no special formatting. 

MOVX AC1..PRI0U ;use primary output 

MOVE AC2.NUMB ;get number from location NUMB 

MOVX AC3, A D10 ;no special format, decimal radix 

N0UT% ; print number 

EJSHLT junexpected fatal error. Halt 

;and print message. 

Refer to Section 1.2.2 for information concerning error returns. The 
following example illustrates the use of the three monitor calls 
described so far, as well as the TMSG macro. The RESET* and HALTF% 
monitor calls are described in Section 2.6. 



SEARCH MONSYM 

SEARCH MACSYM 

.REQUIRE SYS!MACREL 

AC1== = 1 

AC2==2 

AC3=-3 
START! RESETZ (prepare program envi ronment 

HRROI AClrtASCIZ/PLEASE TYPE A DECIMAL NUMBER! /] 

PS0UT2 

MOVEI AClt.PRIIN isource designator 

MOVEI AC3,~D10 (decimal rsdi:: 

NIN% 
ERJMPS ERROR iif input error print mess33e> halt. 

TMSG <THE OCTAL EQUIVALENT IS > 

MOVEI ACIt.PRIOU i destination designator 

MOVEI AC3f"D3 (octal r3dix 

NOUTZ 
EJSHLT ifstal error. Same as ERJMPS ERROR. 

HALTF% J return to command Ian3u32e 

JRST START (begin aiaim if continued 

ERROR! TMSG< 
?ERROR-TYPE START TO BEGIN AGAIN> 

HALTF% 

JRST START iuser types cont inue-stsrt 32ain 

END START 



2.6 INITIALIZING AND TERMINATING THE PROGRAM 

Two monitor calls that have not yet been described were used in the 
above program - RESET* and HALTF%. 
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2.6.1 RESET* Monitor Call 

A good programming practice is to include the RESET% monitor call at 
the beginning of every assembly language program. This call closes 
any existing open files and releases their JFNs, kills any inferior 
processes) clears the software interrupt system (see Chapter k) , and 
performs various other process ini ti 1 ization functions. For a 
complete list of the functions provided by the RESET% monitor call, 
refer to the description of the call in the TOPS-20 Moni tor Cal Is 
Reference Manual . The format of the call is 

RESET% 

and control always returns to the next instruction following the call. 



2.6.2 HALTF% Monitor Call 

To stop the execution of a program and return control to the TOPS-20 
Command Language, the user must include the HALTF% monitor call as the 
last instruction performed in the program. The user can then resume 
execution of the program at the instruction following the HALTF% call 
by typing the CONTINUE command after control has returned to command 
level . 



2.7 READING A BYTE 

The PBIN% (Primary Byte Input) monitor call is used to read a single 
byte (that is, one character) from the terminal. The user's program 
does not have to specify the source and destination for the byte 
because this call uses the primary input designator (that is, the 
user's terminal) as the source and accumulator 1 as the destination. 
After execution of the PBIN% call, control returns to the instruction 
following the PBIN%. If execution of the call is successful, the byte 
read from the terminal is right-justified in AC1. If execution of the 
call is not successful, an illegal instruction trap is generated, as 
explained in Section 1.2.2. 



2.8 WRITING A BYTE 

The PB0UT% (Primary Byte Output) monitor call is used to write a 
single byte to the terminal. This call uses the primary output 
designator (that is, the user's terminal) as the destination for the 
byte; thus, the user's program does not have to specify the 
destination. The source of the byte being written is accumulator 1; 
therefore, the user's program must place the byte right-justified in 
AC1 before the cal 1 . 
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After execution of the PB0UT% call, control returns to the instruction 
following the PB0UT%. If execution of the call is successful, the 
byte is written to the user's terminal. If execution of the call is 
not successful, an illegal instruction trap is generated, as explained 
in Section 1.2.2. 



2.9 READING A STRING 

Up to this point, monitor calls have been presented for printing a 
string, reading and writing an integer, and reading and writing a 
byte. The next call to be discussed obtains a string from the 
terminal and, in addition, allows the user at the terminal to edit his 
input as he is typing it. 

| The RDTTY% (Read from Terminal) monitor call reads input from the 
I user's terminal (that is, from -PR I I N) into the program's address 
space. Input is read until the user either types an appropriate 
terminating (break) character or inputs the maximum number of 
characters allowed in the string, whichever occurs first. Output 
generated as a result of character editing is printed on the user's 
| terminal (that is, output to .PRIOU). 

The RDTTY% call handles the following editing functions: 

1. Delete the last character in the string if the user presses 
the DELETE key while typing his input. 

2. Delete back to the last punctuation character in the string 
if the user types CTRL/W while typing his input. 

3. Delete the current line if the user types CTRL/U while typing 
his input. 

k. Retype the current line if the user types CTRL/R while typing 
his input. 

Because the RDTTY% call can handle these editing functions, a program 
can accept input from the terminal and allow this input to be 
corrected by the user as he is typing it. For this reason, the RDTTY 
call should be used to read input from the terminal before processing 
that input with calls such as NIN%. 
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The RDTTY% call accepts three words of arguments in AC1 through AC3. 

AC1: pointer to area in program's address space where input is 
to be placed. This area is called the text input buffer. 

AC2: control bits in the left half, and maximum number of bytes 
in the text input buffer in the right half. 

AC3: pointer to buffer for text to be output before the user's 
input if the user types a CTRL/R, or i f only the user's 
input is to be output on a CTRL/R. 

The control bits in the left half of AC2 specify the characters on 
which to terminate the input. These bits are described in Table 2-2. 



Table 2-2: RDTTY% Control Bits 



Bit 



Symbol 



Meaning 



RD%BRK 

1 RD%T0P 



Terminate input when user types a 
CTRL/Z or presses the ESC key. 

Terminate input when user types one of 
the fol lowing: 

CTRL/G 
CTRL/L 
CTRL/Z 
ESC key 
RETURN key 
Line feed key 
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Table 2-2: RDTTY% Control Bits (Cont.) 



Bit 



Symbol 



Meani ng 



RD%PUN 



Terminate input when user types one of 
the fol lowi ng: 



CTRL/A-CTRL/F 
CTRL/H-CTRL/I 
CTRL/K 

CTRL/N-CTRL/Q 
CTRL/S-CTRL/T 
CTRL/X-CTRL/Y 
ASCI I codes 3^-36 
ASCI I codes UO-57 
ASCI I codes 72-100 
ASCI I codes 133- HO 
ASCI I codes 173-176 

The ASCII codes listed above represent 
the punctuation characters in the 
ASCI I character set. Refer to the 
ASCII character set table in Appendix 
A of the TOPS-20 Monitor Cal Is 
Reference Manual for these characters. 



R0%BEL 



Terminate input when user types the 
RETURN or line feed key (that is, end 
of 1 i ne) . 



RD%CRF 



RD%RND 



Store only the line feed in the input 
buffer when the user presses the 
RETURN key. A carriage return will 
still be output to the terminal but 
will not be stored in the buffer. If 
this bit is not set and the user 
presses the RETURN key, both the 
carriage return and the line feed will 
be stored as part of the input. 

Return to program if the user attempts 
to delete past the beginning of his 
input. This allows the program to 
take control if the user tries to 
delete all of his input. If this bit 
is not set, the program waits for more 
input. 

Reserved for Digital (must be 0). 
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Table 2-2: RDTTY% Control Bits (Cont.) 



Bit 



Symbol 



RD%R I E 



8 
9 

10 
11 



RD%BEG 

RD%RAI 
RD%SUI 



15 



RD%NED 



Meaning 



Return to program when there is no 
input (that is, the text input buffer 
is empty). If this bit is not set, 
the program waits for more input. 

Reserved for Digital (must be 0). 

Return to user program if the user 
attempts to edit beyond the beginning 
of the input buffer. 



Convert 
case. 



lower case input to 



upper 



Suppress the CTRL/U indication on the 
terminal when a CTRL/U is typed by the 
user. This means that if the user 
types a CTRL/U, XXX will not be 
printed and, on display terminals, the 
characters will not be deleted from 
the screen. If this bit is not set 
and the user types a CTRL/U, XXX will 
be printed and, if appropriate, the 
characters will be deleted from the 
screen. In neither case is the CTRL/U 
stored in the input buffer. 

Disable editing characters in user 
break mask. If this bit is set, then 
any editing character (*R, a(j, av, a^, 
and DELETE) in the user supplied break 
mask does not have its editing 
function. 
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If no control bits are set in the left half of AC2, the input will be 
| terminated when the user presses the RETURN or line feed key (that is, 
| terminated on an end-of-line condition only). 

The count in the right half of AC2 specifies the number of bytes 
available for storing the string in the program's address space. The 
input is terminated when this count is exhausted, even if a specified 
break character has not yet been typed. 

The pointer in AC3 is to the beginning of a buffer containing the text 
to be output if the user types a CTRL/R. When this happens, the text 
in this separate buffer is output, followed by any text that has been 
typed by the user. The text in this buffer cannot be edited with any 
of the editing characters (that is, DELETE, CTRL/W, or CTRL/U) . If 
the contents of AC3 is zero, then no such buffer exists, and if the 
user types CTRL/R, only the text in the input buffer will be output. 

| If execution of the RDTTY% call is successful, the input is in the 
specified area in the program's address space. The character that 
terminated the input is also stored. (If the terminating character is 
a carriage return followed by a line feed, the line feed is also 
stored.) Control returns to the user's program at the second location 
following the call. The pointer in AC1 is advanced to the character 
| following the last character stored. The count in the right half of 
| AC2 is updated to reflect the remaining bytes in the buffer, and 
appropriate bits are set in the left half of AC2. The bits that can 
be set on a successful return are: 

Bit 12 RD%BTM The input was terminated because one 

of the specified break characters was 
typed. This break character is placed 
in the input buffer. If this bit is 
not set, the input was terminated 
because the byte count was exhausted. 

Bit 13 RD%BFE Control was returned to the program 

because there is no more input and 
RD%RIE was set in the call. 

Bit 14 RD%BLR The limit to which the user can backup 

for editing his input was reached. 

I For consistent handling of error returns refer to Section 1.2.2. 
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The following example illustrates the recommended method for reading 
data from the terminal. This example is essentially the same as the 
one in Section 2.5; however, the RDTTY% call is used to read the 
number before the NIN% call processes it. This program stores the 
last error encountered in location LASTER and therefore uses the 
ERJMPR pseudo-op. 



SEARCH MONSYM 
SEARCH MACSYM 
.REQUIRE SYS:MACREL 
AC1==1 
AC2==2 

AC3--3 
START: RESET* 

HRROI AC 1, PROMPT 

PS0UT% 

HRROI AC1, BUFFER 

MOVE I AC2,BUFLEN*5 

HRROI AC3, PROMPT 

RDTTY* 
ERJMPR ERROR 

HRROI AC1, BUFFER 

MOVEI AC3, A D10 

NIN% 
ERJMPR ERROR 

TMSG <THE OCTAL EQUIVA 

MOVEI AC1,.PRI0U 

MOVEI AC3, A D8 

N0UT% 
ERJMPR ERROR 

HALTF% 

JRST START 
PROMPT: ASCIZ/PLEASE TYPE A DE 

BUFLEN==10 
BUFFER: BLOCK BUFLEN 
LASTER: BLOCK 1 
ERROR: MOVEM AC1, LASTER 

TMSG < 
TERROR-TYPE START TO BEGIN AGA 

HALTF% 

JRST START 

END START 



;prepare program environment 

;type prompt 

; location to store number 

;size of buffer 

; pointer to prompt 

;read number from term, with editing 

;save error code, print message and halt 

;source designator 

;decimal radix 

;if input error, print message and halt 
LENT IS > 

{destination designator 
;octal radix 

;save error code, print message and halt 
; return to command language 
; beg in again, if continued 
CIMAL NUMBER: / 



;save error code 

IN>;print general error message 
;halt 
;start over if continued 
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2.10 SUMMARY 



Data transfers of sequential bytes or text strings can be made to and 
from the terminal. The monitor calls for transferring bytes are PBIN% 
and PB0UT% and for transferring strings are PS0UT% and RDTTY%. The 
NIN% and N0UT% monitor calls can be used for reading and writing a 
number. In general, the user's program must specify a source from 
which the data is to be obtained and a destination where the data is 
to be placed. In the case of terminal I/O, the symbol .PRIIN 
represents the user's terminal as the source, and the symbol .PRIOU 
represents the user's terminal as the destination. 
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CHAPTER 3 
USING FILES 



3.1 OVERVIEW 

| All information stored in the DECSYSTEM-20 is kept in files. The 
basic unit of storage in a file is a page containing bytes from 1 to 
36 bits in length. Thus, a sequence of pages constitutes a file. In 
most cases, files have names. Although all files are handled in the 
same manner, certain operations are unavailable for files on 
particular devices. 

Programs can reference files by several methods: 

• In a sequential byte-by-byte manner. 

• In a multiple byte or string manner. 

• In a random byte-by-byte manner if the particular 
file-storage device allows it. 



• 



In a page-mapping or section-mapping manner for files on 
di sk . 



Byte and string input/output are the most common types of operations. 

Generally, all programs perform I/O by moving bytes of data from one 
location to another. For example, programs can move bytes from one 
memory area to another, from memory to a disk file, and from the 
user's terminal to memory. In addition, a program can map multiple 
512-word pages or 512-page sections from a disk file into memory or 
vice versa. 
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Data transfer operations on files require four steps: 

1. Establishing a correspondence between a file and a Job File 
Number (JFN) , because all files are referenced by JFNs. 

2. Opening the file to establish the data mode, access mode, and 
byte size and to set up the monitor tables that permit data 
to be accessed. 

3. Transferring data either to or from the file. 

k. Closing the file to complete any I/O, to update the directory 
if the file is on the disk, and to release the monitor table 
space used by the file. 

Some operations on files do not require the execution of all four 
steps above. Examples of these operations are: deleting or renaming 
a file, or changing the access code or account of a file. Although 
these operations do not require all four steps, they do require that 
the file has a JFN associated with it (step 1 above). 

It is possible for disk files on the DECSYSTEM-20 to be simultaneously 
read or written by any number of processes. To make sharing of files 
possible, all instances of opening a specific file in a specific 
directory cause a reference to the same data. Therefore, data written 
into a file by one process can immediately be seen by other processes 
readi ng the file. 

Access to files is controlled by the 6-digit (octal) file access code 
assigned to a file when it is created. This code indicates the types 
of access allowed to the file for the three classes of users: the 
owner of the file, the users with group access to the file, and all 
other users. (Refer to the TOPS-20 User's Guide for more information 
on the file access codes.) If the user is allowed access to a file, he 
requests the type of access desired when opening the file with the 
0PENF% monitor call (refer to Section 3.^.1) in his program. If the 
access requested in the 0PENF% call does not conflict with the current 
ccess to the file, the user is granted access. Essentially, the 
rrent access to the file is set by the first user who opens it. 



a 

cu 



Thus, for a user to be granted access to a specific file, two 
conditions must be met: 

1. The file access code must allow the user to access the file 
in the desired manner (for example, read, write). 

2. The file must not be opened for a conflicting type of access. 
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3.2 JOB FILE NUMBER 

The Job File Number (JFN) is one of the more important concepts in the 
operating system because it serves as the identifier of a particular 
file on a particular device during a process' execution. It is a 
small integer assigned by the system upon a request from the user's 
program. JFNs are usually assigned sequentially starting with 1. 

The JFN is valid for the job in which it is assigned and may be used 
by any process in the job. The system uses the JFN as an index into 
the table of files associated with the job and always assigns a JFN 
that is unique within the job. Even though a particular JFN within 
the job can refer to only one file, a single file can be associated 
with more than one JFN. This occurs when two or more processes are 
using the same file concurrently. In this case, each of the processes 
will probably have a different JFN for the file, but all of the JFNs 
will be associated with the same file. 



3.3 ASSOCIATING A FILE WITH A JFN 

In order to reference a file, the first step the user program must 
complete is to associate the specific file with a JFN. This 
correspondence is established with the GTJFN% (Get Job File Number) 
monitor call. One of the arguments to this call is the string 
representing the desired file. The string can be specified within the 
I program (that is, come from memory) or can be accepted as input from 
the user's terminal or from another file. The string can represent 
the complete specification for the file: 

I dev:<directory>name.typ.gen;T(temporary) ;P (protection) ;A(account) ; 
j (device dependent attributes) 

I If you omit any fields of the specification, the system can provide 
I values for all except the name field. Refer to the TOPS-20 User's 
j Guide for a complete explanation of the specification for a file. 

Table 3-1 lists the values the system will assign to fields not 
specified by the input string. 
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Table 3-1: Standard System Values For File Specifications 



Field 



Value 



Device 
Directory 

Name 

Type 

Generation number 



Protection 



Account 



DSK: 

Directory to which user is currently 
connected. 

No default; this field must be 
speci f ied. 

Null . 

The highest existing generation number 
if the file is an input file. The 
next higher generation number if the 
file is an output file. 

Protection of next lower generation of 
file, if one exists; otherwise, 
protection as specified in the 
di rectory. 

Account specified when user logged in. 



If the string specified identifies a single file, the monitor returns 
a JFN that remains associated with that file until either the process 
releases the JFN or the job logs off the system. After the assignment 



of the JFN is complete, 
references to that file. 



the user's program uses the JFN in all 



The user's program can set up either the short or the long form of the 
GTJFN% monitor call. The long form of the GTJFN% call requires an 
argument block; the short form does not. The long form of GTJFN% has 
functions and flexibility not available in the short form of the call. 
The short form of GTJFN% allows a file specification to be obtained 
from a string in memory or from a file, but not from both. Fields not 
specified by the input are taken from the standard system values for 
those fields (refer to Table 3-1). This form is sufficient for most 
uses of the call. The long form allows a file specification to be 
obtained from both a string in memory and a file. If both are given 
as arguments, the string is used first, and then the file is used if 
more fields are needed to complete the specification. This form also 
allows the user's program to specify nonstandard values to be used for 
fields not given and to request the assignment of a specific JFN. 
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3.3-1 GTJFN% Monitor Call 

The GTJFN% monitor call assigns a JFN to the specified file. It 
accepts two words of arguments. These argument words are different 
depending on the form of GTJFN% being used. The user's program 
indicates the desired GTJFN% form by setting bit 17(GJ%SHT) of AC1 to 
1 for the short form or by clearing bit 17(GJ%SHT) for the long form. 



3.3.1.1 Short Form Of GTJFNfc - The short form of the GTJFN% monitor 
call requires the following two words of arguments. 



AC1 












!== 


BBXSBEIBKBXBMBS 


1 


flag 


bi 


its 



17 18 35 

:SESC«BS£SfiBBHCSKlKaESKSfiM81«KaiSfi33exfiSCXtXfiS2aB j 

! default generation number ! 



!« 



MBBBSSBSBMBSCSKBC 1 



AC2 





I 
! 



35 



source designator for file specification per 
bit 16 (GJ%FNS) of AC1 



The flag bits that can be specified in AC1 are described in Table 3~2. 



Table 3-2: GTJFN% Flag Bits 



Bit 



Symbol 



Meani ng 



GJ%F0U 



The file specification given i s to be 
assigned the next higher generation 
number. This bit indicates that a new 
version of a file is to be created and 
is normally set if the file is for 
output use. 



GJ%NEW 



The file specification given must not 
refer to an existing file (that is, 
the file must be a new file) . 



GJ%0LD 



The file specification given must 
refer to an existing file. This bit 
has no effect on a parse-only JFN. 
(See bit GJ%0FG.) 
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Table 3-2: GTJFNfc Flag Bits (Cont.) 



Bit 



Symbol 



Meaning 



GJ%MSG 



One of the appropriate messages is to 
be printed after the file 
specification is obtained. The 
message is printed only if the user 
types the ESC key to end his file 
specification (that is, he is using 
recognition input). 

[NEW FILE] 

[NEW GENERATION] 

[OLD GENERATION] 

[OK] if GJ%CFM (bit k) is off 

[CONFIRM] if GJ%CFM (bit It) i s on 



GJ%CFM 



Confirmation from the user will be 
required to verify that the file 
specification obtained is correct. To 
confirm the file specification, the 
user can press the RETURN key. 



5 
6 



GJfcTMP 
GJ%NS 



The file speci f ied 
temporary file. 



i s 



to be 



Only the first file specification in a 
multiple logical name assignment is to 
be searched for the file. 



GJ%ACC 



The JFN specified is not to be 
accessed by inferior processes in this 
job. However, any process can access 
the file by acquiring a different JFN. 
To prevent the file from being 
accessed by other processes, the 
user's program can set 0F%RTD (bit 29) 
in the OPENF call (refer to Section 
3.^.1) • 



GJfcDEL 



The file specified is not to be 
considered as deleted, even if it is 
marked as deleted. 



9-10 



GJ%JFN 



These bits are off in the short form 
of the GTJFN call (refer to Section 
3-3-1-2 for their description). 
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Table 3~2: GTJFN% Flag Bits (Cont.) 



Bit Symbol Meaning 



11 GJ%IFG The file specification given is 

allowed to have one or more of its 
fields specified with a wildcard 
character (* or %) . This bit is used 
to process a group of files and is 
generally used for input files. The 
monitor verifies that at least one 
value exists for each field that 
contains a wildcard and assigns the 
JFN to the first file in the group. 

The monitor also verifies that fields 
not containing wildcards reprsent a 
new or old file according to the 
setting of GJ%NEW and GJ%0LD. 

12 GJ%0FG The JFN is to be associated with the 

given file specification string only 
and not to the actual file. The 
string may contain a wildcard 
character (* or %) in one or more of 
its fields. It is checked for correct 
punctuation between fields, but is not 
checked for the validity of any field. 
This bit allows a JFN to be associated 
with a file specification even if the 
file specification does not refer to 
an actual file. The JFN returned 
cannot be used to refer to an actual 
file (for example, cannot be used in 
an OPENF call) but can be used to 
obtain the original input string via 
the JFNS monitor call (refer to 
Section 3-7-2) . 

13 GJ%FLG Flags are to be returned in the left 

half of AC1 on a successful return. 
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Table 3-2: GTJFN% Flag Bits (Cont.) 



Bit 



Symbol 



Meani ng 



14 



15 



16 



GJ%PHY 



GJ%XTN 



GJ%FNS 



Logical names specified for the 
current job are to be ignored and the 
physical device is to be used. 

This bit is off in the short form of 
the GTJFN call (refer to Section 
3-3- 1 -2 for its description). 



The contents of AC2 
interpreted as follows: 



are 



to 



be 



1. If this bit is on, AC2 conta 
input JFN in the left half 
output JFN in the right half 
input JFN is used to obta 
file specification to 
associated with the JFN. 
output JFN is used to indica 
destination for printing the 
of any fields being recog 
To omit either JFN, the 
program must specify the 
.NULIO (377777) • 



ins an 
and an 
. The 
the 
be 
The 
the 
names 
nized. 
user ' s 
symbol 



i n 



te 



17 



GJfcSHT 



2. If this bit is off, AC2 contains a 
pointer to a string in memory that 
specifies the file to be 
associated with the JFN. 

This bit must be on (set) for the 
short form of the GTJFN% call; it must 
be off for the long form of the call. 
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Table 3-2; GTJFN% Flag Bits (Cont.) 



Bit 



Symbol 



18-35 



Meaning 



The generation number of the file 
(between 1 and 377777) or one of the 
fol lowing: 

O(.GJDEF) to indicate that the next 
higher generation number 
of the file is to be used 
if GJ%F0U (bit 0) is on, 
or to indicate that the 
highest existing 

generation number of the 
file is to be used if 
GJ%F0U is off. (This 
value is usually used in 
this field.) 

-1 (.GJNHG) to indicate that the next 
higher generation number 
of the file is to be used 
if no generation number is 
suppl ied. 

-2(.GJLEG) to indicate that the 
lowest existing generation 
number of the file is to 
be used. 

-3(.GJALL) to indicate that all 
generation numbers (*) of 
the file are to be used 
and that the JFN is to be 
assigned to the first file 
in the group. (Bit GJ%IFG 
must be set.) 
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If the GTJFN% call is given with the appropriate flag bit set (GJ%IFG 
or GJ%0FG) , the file specification given as input can have a wildcard 
character (either an asterisk or a percent sign) appearing in the 
directory, name, type, or generation number field. (The percent sign 
cannot appear in the generation number field.) The wildcard character 
is interpreted as matching any existing occurrence of the field. For 
example, the specification 

<LIBRARY>*.MAC 

identifies all the files with the file type .MAC in the directory 
named <LIBRARY>. The specification 

<LIBRARY>MYFILE.FO% 

identifies all the files in directory <LIBRARY> with the name MY F I L E 
and a three-character file type in which the first two characters are 
.FO. Upon completion of the GTJFN call, the JFN returned is 
associated with the first file found in the group according to the 
fol lowi ng: 

• in numerical order by directory number 

• in alphabetical order by filename 

• in alphabetical order by file type 

• in ascending numerical order by generation number 

The GNJFN% (Get Next JFN) monitor call can then be given to assign the 
JFN to the next file in the group (refer to Section 3.7.3). Normally, 
a program that accepts wildcard characters in a file specification 
will successively reference all files in the group using the same JFN 
and not obtain another JFN for each one. 

If execution of the GTJFN% call is not successful because problems 
were encountered in performing the call, the JFN is not assigned and 
an error code is returned in the right half of AC1. The execution of 
the program continues at the instruction following the GTJFN% call. 

If execution of the GTJFN% call is successful, the JFN assigned is 
returned in the right half of AC1 and various bits are set in the left 
half, if flag bits 11, 12, or 13 were on in the call. (The bits 
returned on a successful call are described in Table 3~3.) If bit 11, 
12, or 13 was not on in the call, the left half of AC1 is zero. The 
execution of the program continues at the second instruction after the 
GTJFN% call. 
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Table 3~3: Bits Returned on GTJFN% Call 



Bit 



Symbol 



Meaning 



GJ%DEV 



The device field of the file 
specification contains wildcard 
characters. 



GJ%UNT 



The unit field of the file 
specifications contains wildcard 
characters. This bit is never set 
because wildcard characters are not 
allowed in unit fields. 



GJ%DIR 



The directory field of the file 
specification contains wildcard 
characters. 



GJ%NAM 



The filename field of the file 
specification contains wildcard 
characters. 



GJ%EXT 



The file type field of the file 
specification contains wildcard 
characters. 



GJ%VER 



The generation number field of the 
file specification contains wildcard 
characters. 



GJ%UHV 



GJ%NHV 



The file used has the highest 
generation number because a generation 
number of was given in the call. 

The file used has the next higher 
generation number because a generation 
number of or -1 was given in the 
cal 1 . 



GJ%ULV 



The file used has the lowest 
generation number because a generation 
number of -2 was given in the call. 



10 



GJ%PR0 



GJ%ACT 



The protection field of the 
specification was given. 



The account field of 
specification was given. 



file 



the file 
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Table 3-3: Bits Returned on GTJFN% Call (Cont.) 



Bit 



Symbol 



Meaning 



11 
12 



13 
17 



GJ%TFS 
GJ%GND 



GJ%N0D 
GJ%GIV 



The file specification is for a 
temporary file. 

Files marked for deletion are not 

considered when assigning JFNs in 

subsequent calls. This bit is set if 
GJ%DEL was not set in the call. 

The node name field of the file 
specification was given. 

Invisible files were not considered 
when assigning JFNs. 



Examples of the short form of the GTJFN% monitor call are shown in the 
following paragraphs. 

The following sequence of instructions is used to obtain, from the 
user's terminal, the specification of an existing file. 

MOVX AC1,GJ%0LD+GJ%FNS+GJ%SHT 
MOVE AC2,[.PRI IN,,.PRI0U] 
GTJFN% 

The bits specified for AC1 indicate that the file specification given 
must refer to an existing file (GJ%0LD) , that the file specification 

is to be accepted from the input JFN in AC2 (GJ%FNS) , and that the 
short form of the GTJFN% call is being used (GJ%SHT) . Because the 
right half of AC 1 is zero, the standard generation number algorithm 
will be used. In this GTJFN% call, the file with the highest existing 
generation number is used. Because GJ%FNS is set in AC1, the contents 
of AC2 are interpreted as containing an input JFN and an output JFN. 

In this example, the file specification is obtained from the terminal 

(.PRI IN) . 

The following sequence of instructions is used to obtain, from the 

user's terminal, the specification of an output file and to require 

confirmation from the user once the file specification has been 
obtai ned. 

MOVX AC1 ,GJ%FOU+GJ%MSG+GJ%CFM+GJ%FNS+GJ%SHT 

MOVE AC2.C.PRI IN...PRI0U] 

GTJFN% 
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In this example, the bits specified for AC1 indicate that 

• the file obtained is to be an output file (GJ%F0U) , 

• after the file specification is obtained, a message is to be 
typed (GJ%MSG) , 

• the user is required to confirm the file specification that 
was obtained (GJ%CFM) , 

• the file specification is to be obtained from the input JFN 
in AC2 (GJ%FNS) , 

• the short, form of the GTJFN% call is being used (GJ%SHT) . 

Because the right half of AC1 is zero, the generation number given to 
the file will be one greater than the highest generation number 
existing for the file. The contents of AC2 are interpreted as 
containing an input JFN and an output JFN because GJ%FNS is set in 
AC1. 

The following sequence of instructions is used to obtain the name of 
an existing file from a location in the user's program. 

MOVX AC1,GJ%0LD+GJ%SHT 
MOVE AC2, [POINT 7. NAME] 
GTJFN% 



NAME:ASCIZ/MYFILE..TXT/ 

The bits specified for AC1 indicate that the file obtained is to be an 
existing file (GJ%0LD) and that the short form of the GTJFN% call is 
being used (GJ%SHT) . Since the right half of AC1 is zero, the file 
with the highest generation number will be used. Because GJ%FNS is 
not set, the contents of AC2 are interpreted as containing a pointer 
to a string in memory that specifies the file to be associated with 
the JFN. The setup of AC2 indicates that the string begins at 
location NAME in the user's program. The file specification obtained 
from location NAME is MYFILE.TXT. 
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An alternate way of specifying the same file is the sequence 

MOVX AC1,GJ%0LD+GJ%SHT 

HRROI AC2,[ASCIZ/MYFILE.TXT/] 

GTJFN% 



3.3.1.2 Long Form Of GTJFN% - The long form of the GTJFN% monitor 
call requires the following two words of arguments: 



17 18 35 

AC1 ! ! address of argument table ! 



35 

AC2 ! pointer to ASCIZ file specification string, or ! 



j The argument block for the long form is described in Table J>-k, 
Table 3 -i *: Long Form GTJFN% Argument Block 

Word Symbol Meaning 



.GJGEN Flag bits appear in the left half and 

generation number appears in the right 
half. 

•GJSRC An input JFN appears in the left half 

and an output JFN appears in the right 
half. To omit either JFN, the user's 
program must specify the symbol .NULIO 
(377777) . 

.GJDEV Pointer to ASCIZ string that specifies 

the device to be used when none is 
given. If this word is 0, DSK will be 
used. 
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Table 3-4: Long Form GTJFN% Argument Block (Cont.) 



Word 



Symbol 



.GJDIR 



.GJNAM 



Meaning 



Pointer to ASCIZ string that specifies 
the directory to be used when none is 
given. If this word is 0, the user's 
connected directory will be used. 

Pointer to ASCIZ string that specifies 
the filename to be used when none is 
given. If this word is G, the input 
must specify the filename. 



.GJEXT 



Pointer to ASCIZ string that specifies 
the file type to be used when none is 
given. If this word is 0, a null type 
will be used. 



.GJPRO 



Pointer to ASCIZ string or 3B2+octal 
protection code. This word indicates 
the protection to be used when none is 
given. If this word is 0, the 
protection as specified in the 
directory will be used. 



.GJACT 



Pointer to ASCIZ string 
account number. This 
the account to be used 
given. If thi s word is 
specified when the user 
be used. 



or 3B2+decimal 
word indicates 
when none is 
0, the account 
logged in will 



10 



.GJJFN 



11-17 



The JFN to assign to the file 
specification if flag bit GJ%JFN is 
set in word .GJGEN (word 0) of the 
argument block. 

Additional words allowed if flag bit 
GJ%XTN (bit 15) is set in word .GJGEN 
(word 0) of the argument block. These 
additional words are used when 
performing command input parsing and 
are described in the T0PS-20 Monitor 
Cal Is Reference Manual. 
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The flag bits accepted in the left half of .GJGEN (word 0) of the 
argument block are the same as those accepted in the short form of the 
GTJFN% call. The entire set of flag bits is listed in Table 3-2. 

The generation number values accepted in the right half of .GJGEN 
(word 0) of the argument block can be 0, -1, -2, -3, or a specified 
number, although is the normal case. Refer to Bits 18-35 of Table 
3-2 for explanations of these values. 

If execution of the GTJFN% call is successful, the JFN assigned is 
returned in the right half of AC1 and various bits are set in the left 
half if flag bits 11, 12 or 13 were on in the call. Refer to Table 
3~3 for the explanations of the bits returned. Execution of the 
program continues at the second instruction following the call. 

If execution of the GTJFN call is not successful, the JFN is not 

assigned and an error code is returned in the right half of AC1. The 

execution of the program continues at the instruction following the 
GTJFN% call. 

The following sequence of instructions obtains a specification for an 
existing file from the user's terminal, assigns the JFN to the next 
higher generation of that file, and specifies default fields to be 
used if the user omits a field when he gives his file specification. 

MOVE I AC1.JFNTAB 
SETZ AC2, 
GTJFN% 



JFNTAB: GJ%F0U 

XWD .PR I IN..PRI0U 



POINT 7.CASCIZ/TRAIN/] ;default directory 



POINT 7.CASCIZ/MEM/] ;default file type 
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The address of the argument table for the GTJFN% call (JFNTAB) is 
given in the right half of AC1. AC2 contains 0, which means no 
pointer to a string is given; thus, fields for the file specification 
will be taken only from the user's terminal. The first word of the 
argument block contains a flag bit for the GTJFN% call. This bit 
(GJ%F0U) indicates that the next higher generation number is to be 
assigned to the file. The second word of the argument block indicates 
that the file specification is to be obtained from the user's 
terminal, and any output generated because of the user employing 
recognition is to be printed on his terminal. If the user does not 
supply a directory name as part of his file specification, the 
directory <TRAIN> will be used. And if the user does not give a file 
type, the type MEM will be used. If the user omits other fields from 
his specification, the system standard value (refer to Table 3-1) will 
be used. 



3.3.1.3 Summary Of GTJFN% - The GTJFN% monitor call is required to 
associate a JFN with a particular file. In most cases, the short form 
of the GTJFN% call is sufficient for establishing this association. 
However, the long form is more powerful because it provides the user's 
program more control over the file specification that is obtained. 
The following summary compares the characteristics of the two forms of 
the GTJFN% monitor call. 



Short Form 



Long Form 



Assigns a JFN to a file. 
System decides the JFN 
to assign. 



Assigns a JFN to a file. 
User program may request 
a particular JFN. 



Accepts the file specification 
from a string in memory 
or a file. 



Accepts the file specification 
from a string in memory 
and a file. 



Uses standard system values 
for fields not given 
i n the file 
spec! f icat ion. 



Allows user-supplied values 
to be used for fields not 
given i n the file 
specif icat ion. 



3. A OPENING A FILE 

Once a JFN has been obtained for a file, the user's program must open 
the file in order to transfer data. The user's program supplies the 
JFN of the file to be opened and a word of bits indicating the desired 
byte size, data mode, and access to the file. 



3-17 



USING FILES 



The desired access to the file is specified by a separate bit for each 
type of access. The file is successfully opened only if the desired 
access does not conflict with the current access to the file (refer to 
Section 3.1). For example, if the user requests both read and write 
access to the file, but write access is not allowed, then the file is 
not opened for this user. The allowed types of access to a file are: 

• Read access. The file can be read with byte, string, or 
random input. 

• Write access. The file can be written with byte, string, or 
random output. 

• Append access. The file can be written only with sequential 
byte or dump output, and the current byte pointer (refer to 
Section 3 • 5 - 1 ) cannot be changed. The initial position of 
the file pointer is at the end of the file. 

• Frozen access. The file can be concurrently accessed by at 
most one user writing the file, but by any number of users 
reading the file. This is the default access to a file. 

• Thawed access. The file can be accessed even if other users 
are reading and writing the file. 

• Restricted access. The file cannot be accessed if another 
user already has opened the file. 

• Unrestricted read access. The file can be read regardless of 
what other users might be doing with the file. 



3-^.1 0PENF% Monitor Call 

The 0PENF% (Open File) monitor call opens a specified file. It 
requires the following two words of arguments. 



17 18 35 

AC! ! ! JFN of file to be opened ! 



5 6 9 18 30 31 35 

AC2 ! byte idata ! ! access bits ! ! 
! size Imode ! ! ! ! 
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If the left half of AC1 is not 0, the contents of AC1 is interpreted 
as a pointer to a string, not as a JFN. If the user's program 
requests bits returned in AC1 from the GTJFN% call, these bits must be 
cleared before executing the 0PENF% call. 

The byte size (0F%BSZ) in AC2 specifies the number of bits in each 
byte of the file and can be between 1 and 36 (decimal). If this field 
is a byte size of 36 (decimal) is assumed. 

The file data mode field (0F%M0D) usually has one of two values: 

Value Meaning 





17 



Normal data mode of the file (that is, byte 
I/O) . Dump I/O is i 1 legal . 

Dump mode (that is, unbuffered word I/O). 
Byte I/O is illegal and the byte size is 
ignored. 



The access bits are described in Table 3-5. 



Table 3~5: 0PENF% Access Bits 



Bit 



Symbol 



Meaning 



i 0-5 
I 6-9 
18 



0F%BSZ 
0F%M0D 
0F%HER 



19 


0F%RD 


20 


0F%WR 


21 


0F%EX 


22 


0F%APP 



Byte size (maximum of 36 decimal). 

Data mode in which to open file. 

Halt on the occurrence of an I/O 
device or medium error during 
subsequent I/O to the file. If this 
bit is not set, a software interrupt 
is generated if a device or medium 
error occurs during subsequent I/O. 

Al low read access . 

Al low wr i te access. 

Allow execute access. 

Allow append access. 
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Table 3"5: OPENF% Access Bits (Cont.) 



Bit 



Symbo 1 



Meaning 



23 
2k 

25 
26 



32 
33 



OFfcRDU 



0F%THW 



0F%AWT 



27 


0F%PDT 


28 


0F%NWT 


29 


0F%RTD 


30 


0F%PLN 


31 


0F%DUD 



OFfcOFL 
0F%FDT 

0F%RAR 



Allow unrestricted read access. 

Reserved for Digi tal . 

Allow thawed access. If this bit is 
not set, the file is opened for frozen 
access. 

Block (that is, temporarily suspend) 
the program until access to the file 
is permitted. 

Do not update the access dates of the 
f i le. 

Return an error if access to the file 
cannot be permitted. 

Allow access to the file to only one 
process (that is, restricted access). 

Do not check for line numbers in the 
file. 

Suppress system updating of modified 
pages in memory to thawed files on 
disk unless CLOSF or UFPGS issued. 

Open device even if off-line. 

Force update of . FBREF (last read) in 
FDB and increment RH of .FBCNT (number 
of references) . 

Wait if f i le off-1 ine. 



If bits 0F%AWT and 0F%NWT are both off, an error code is returned if 
access to the file cannot be permitted (that is, the action taken is 
identical to 0F%NWT being on). 
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If execution of the 0PENF% monitor call is successful, the file is 
opened, and the execution of the program continues at the second 
instruction after the OPENFfc call. 

If execution of the 0PENF% call is not successful, the file is not 
opened, and an error code is returned in AC1. The execution of the 
program continues at the next instruction after the 0PENF% call. 

Two samples of the 0PENF% call follow. 

The sequence of instructions below opens a file for input. 

HRRZ AC1.JFNEXT 

MOVX AC2,FLD(ltA,0F%BSZ)+0F%RD+0F%PLN 

OPENFfc 

The JFN of the file to be opened is contained in the location 
indicated by the address in AC1 (JFNEXT) . The bits specified for AC2 
indicate that the byte size is one word FLD (M,0F%BSZ) , that read 
access is being requested to the file (0P%RD) , and that no check will 
be made for line numbers in the file; that is, the line numbers will 
not be discarded (0F%PLN) . Because bit 0F%THW is not set, the file 
can be accessed for reading by any number of processes. 

The following sequence of instructions can be used to open a file 
output. 



for 



MOVE ACT, JFN 

MOVX FLD(7,0F%BSZ)+0F%HER+0F%WR+0F%AWT 

0PENF% 

The right half of AC1 contains the address that has the JFN of the 
file to be opened. The bits specified for AC2 indicate that the byte 
size is 7-bit bytes FLD (7,0F%BSZ) , that the program is to be halted 
when an I/O error occurs in the file (0F%HER) , that write access is 
being requested to the file (0F%WR) , and that the program is to be 
blocked if access cannot be granted (0F%AWT) . Because bit 0F%THW is 
not set, if another user has been granted write access to the file, 
this user's program will be blocked until access can be granted. 



3-5 TRANSFERRING DATA 

Data transfers of sequential bytes are the most common form of 
transfer and can be used with any file. For disk files, nonsequential 
bytes and entire pages can also be transferred. 
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3.5.I File Pointer 

Every open file is associated with a pointer that indicates the last 
byte read from or written to the file. When the file is initially 
opened, this pointer is normally positioned before the beginning of 
the file so that the first data operation will reference the first 
byte in the file. The pointer is then advanced through the file as 
data is transferred. However, if the file is opened for append-only 
access (bit 0F%APP set in the 0PENF% call), the pointer is positioned 
after the last byte of the file. This allows the first write 
operation to append data to the end of the file. 

For disk files, the pointer may be repositioned arbitrarily throughout 
the file, such as in the case of nonsequential data transfers. When 
the pointer is positioned beyond the end of the file, an end-of-file 
indication is returned when the program attempts a read operation 
using byte input. When the program performs a write operation beyond 
the end of the file using byte output, the end-of-file indicator is 
updated to point to the end of the new data. However, if the program 
writes pages beyond the end of the file with the PMAP% monitor call 
(refer to section 3-5-6) , the byte count is not updated. Therefore, 
it is possible for a file to contain pages of data beyond the 
end-of-file indicator. To allow sequential I/O to be performed later 
to the file, the program should update the byte count before closing 
the file. (Refer to the CHFDB% monitor call description in the 
TOPS-20 Monitor Cal Is Reference Manual .) 



3.5-2 Source And Destination Designators 

Because I/O operations occur by moving data from one location to 

another, the user's program must supply a source and a destination for 

any I/O operation. The most commonly-used source and destination 
designators are the following: 

1. A JFN associated with a particular file. The JFN must be 
previously obtained with the GTJFN% or GNJFN% monitor call 
before it can be used. 

2. The primary input and output designators . PR I I N and .PRIOU, 
respectively (refer to Section 2.2). These designators 
should be used when referring to the terminal. 
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3. A byte pointer to the beginning of the string of bytes in the 
program's address space that is being read or written. The 
byte pointer can take one of two forms: 

• A word with a -1 in the left half and an address in the 
right half. This form is used to designate a 7-bit ASCIZ 
string starting in the left-most byte of the specified 
address. A word in this form is functionally equivalent 
to a word assembled by the POINT 7, ADR pseudo-op. 

• A full word byte pointer with a byte size of 7 bits. 

Most monitor calls dealing with strings deal specifically with ASCII 
strings. Normally, ASCII strings are assumed to terminate with a byte 
of (that is, are assumed to be ASCIZ strings). However some calls 
optionally accept an explicit byte count and/or terminating byte. 
These calls are generally ones that handle non-ASCII strings and byte 
sizes other than 7 bits. 



3.5.3 Transferring Sequential Bytes 

The BIN% (Byte Input) and B0UT% (Byte Output) monitor calls are used 
for sequential byte transfers. The BIN% call takes the next byte from 
the given source and places it in AC2. The B0UT% call takes the byte 
from AC2 and writes it to the given destination. The size of the byte 
is that given in the 0PENF% call for the file. 

The BIN% monitor call accepts a source designator in AC1, and upon 

successful execution of the call, the byte is right-justified in AC2. 

If execution of the call is not successful, an illegal instruction 

trap is generated. Control returns to the user's program at the 

I instruction following the BIN% call. If the end of the file is 

I reached, AC2 contains instead of a byte* The program can process 

j this end-of-file condition if a jump style error return is the next 

j instruction following the BIN% call. 

The B0UT% monitor call accepts a destination designator in AC1 and the 
byte to be output, right-justified in AC2. Upon successful execution 
of the call, the byte is written to the destination. If execution of 
the call is not successful, an illegal instruction trap is generated 
Control returns to the user's program at the instruction following the 
B0UT% call. 
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The following sequence shows the transferring of bytes from an input 
file to an output file. The bytes are read from the file indicated by 
INJFN and written to the file indicated by OUTJFN. 



LOOP: MOVE 1, INJFN 
B I N% 
ERJMP DONE 

L00P2: MOVE 1, OUTJFN 
B0UT% 
JRST LOOP 

DONE: GTSTS% 

TXNN 2,GS%E0F 
JRST NOTYET 

N0TYET:M0VEI 2,0 
JRST L00P2 



;get source designator from INJFN 
;read a byte from the source 
;check for end of file, if 
;get destination from OUTJFN 
;write the byte to the destination 
{continue until byte is found 
jobtain status of source 
; test for end of file 
;no, test for in input file 
;yes, process end of file condition 
;0 in i nput file 



3.5-^ Transferring Strings 

The SIN% (String Input) and S0UT% (String Output) monitor calls 
are used for string transfers. These calls transfer either a 
string of a specified number of bytes or a string terminated with 
a specific byte. 

The S I N% monitor call reads a string from the specified source 
into the program's address space. The call accepts four words of 
arguments in AC1 through AC*t. 



AC1 
AC2 
AC3 
AC4 



source designator 

pointer to area in program's address space 
count of number of bytes to read, or 
byte on which to terminate input (optional) 



The contents of AC3 are interpreted as the number of characters to 
read. 

• If AC3 is 0, then reading continues until a byte is found 
in the input. 

• If AC3 is positive, then reading continues until either the 
specified number of bytes is read, or a byte equal to that 
given in AC4 is found in the input, whichever occurs first. 

• If AC3 is negative, then reading continues until minus the 
specified number of bytes is read. 

The contents of kCk needs to be specified only if the contents of AC3 
is a positive number. The byte in AC4 is right-justified. 
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The input is terminated when one of the following occurs: 

• The byte count becomes zero. 

• The specified terminating byte is reached. 

• The end of the file is reached. 

• An error occurs during the transfer (for example, a data 
error occurs) . 

Control returns to the user's program at the instruction following the 
SIN% call. If an error occurs (including the end of the file is 
reached), an illegal instruction trap is generated. In addition, 
several locations are updated: 

1. The position of the file's pointer is updated for subsequent 
I/O to the f i le. 

2. The pointer to the string in AC2 is updated to reflect the 
last byte read or, if AC3 contained 0, the last nonzero byte 
read. 

3. The count in AC3 is updated, if pertinent, by subtracting the 
number of bytes actually read from the number of bytes 
requested to be read (that is, the count is updated toward 
zero). From this count, the user's program can determine the 
number of bytes actually transferred. 

The S0UT% monitor call writes a string from the program's address 
space to the specified destination. Like the SIN% call, this call 
accepts four words of arguments in AC1 through ACU. 



AC1 
AC2 
AC3 
AC*t 



destination designator 

pointer to string to be written 

count of the number of bytes to write, or 

byte on which to terminate output (optional) 



The contents of AC3 and ACA are interpreted in the same manner as they 
are in the SIN% monitor call. 

The transfer is terminated when one of the following occurs. 

• The byte count becomes zero. 

• The specified terminating byte is reached. This terminating 
byte is written to the destination. 

• An error occurs during the transfer. 
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Control returns to the user's program at the instruction following the 
S0UT% call. If an error occurs, an illegal instruction trap is 
generated. In addition, the position of the file's pointer, the 
pointer to the string in AC2, and the count in AC3, if pertinent, are 
also updated in the same manner as in the SIN% monitor call. 

The following code sequence shows transferring a string from an input 
file to an output file. The procedure is the same as at the end of 
Section 3.5-3, using S I N% and S0UT% calls instead of BIN* and BOUT*. 



loop: move i»injfn 
hrroi 2,buf12b 

movni 3»"d12b*s 

SINZ 

ERCAL EOFO 

ADD I 3, "01 28*5 
MOVN 3,3 
MOVE IrOUTJFN 
HRROI 2,BUF128 
SOUTZ 
EOFQJ MOVE 1, IN JFN 
GTSTSZ 

TXNN 2iGSXE0F 
RET 



{•■fet source from INJFN 

J pointer to string to read into (128 

Sword buffer) 

J input a maximum of 640 bytes 

(transfer until en d o f b u f f e r or e n d o f 

{file 

J error occurred 



(determine nesiative number of bates 
{convert to positive 
{set destination from OUTJFN 
{pointer to strins! to write from 
{transfer as many bytes as read 

{obtain status of source 
{test for end of file 
{ n o i c o n t i n u e c o p a i n <■! 



transferred 



3«5-5 Transferring Nonsequential Bytes 

As discussed in Section 3»5-3» the B I N% and B0UT% calls transfer bytes 
sequentially, starting at the current position of the file's pointer. 
The RIN% (Random Input) and R0UT% (Random Output) monitor calls allow 
the user's program to specify where the transfer will begin by 
accepting a byte number within the file. The size of the byte is the 
size given in the 0PENF% call for the file. The RIN% and R0UT% calls 
can only be used when transferring data to or from disk files. 



The R I N% monitor call takes a byte from the specified location in the 
file and places it into the accumulator. The call accepts the JFN of 
the file in AC1 and the byte number within the file in AC3- Upon 
successful completion of the call, the byte is right-justified in AC2, 
and the file's pointer is updated to point to the byte following the 
one just read. If an error occurs, an illegal instruction trap is 
generated. Control returns to the user's program at the instruction 
following the R I N% call. 

The R0UT% monitor call takes a byte from the accumulator and writes it 
into the specified location in the file. The call accepts the JFN of 
the file in AC1, the byte to write right-justified in AC2, and the 
byte number within the file in AC3. Upon successful completion of the 
call, the byte is written into the specified byte in the file, and the 
file's pointer is updated to point to the byte following the one just 
written. If an error occurs, an illegal instruction trap is 



generated, 



fol lowing the ROUT* call . 



Control returns to the user's program at the instruction 
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3.5.6 Mapping Pages 

Up to this point, monitor calls have been presented for transferring 
bytes and strings of data. The next call to be discussed is used to 
transfer entire pages of data between a file and a process. 

Both files and process address spaces are divided into pages of 
512 (decimal) words. A page within a file can be identified by one 
word, where the JFN of the file is in the left half and the page 
number within the file is in the right half. A page within a process 
address space can also be identified by one word, where the identifier 
of the process (refer to Section 5.3) is in the left half and the page 
number within the process' address space is in the right half. Each 
one-word identifier for the pages in the process address space is 
placed in what is called the process page map. When identifiers for 
file pages are placed in the process page map, references to the 
process page actually refer to the file page. The following diagram 
illustrates a process map that has identifiers for pages from two 
f i les. 

File 1 



Process Map 












JFN1 


Page 1 


Page 1 










File 2 






JFN2 


Page 2 


Page 2 
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The PMAP% (Page Mapping) monitor call is used to map one or more 
entire pages from a file to a process (for input), from a process to a 
file (for output), or from one process to another process. In 
general, this call changes the entries in the process map by accepting 
file page identifiers and process page identifiers as arguments. 
Mapping pages between a file and a process is described below; mapping 
pages between two processes is described in Chapter 5. 
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3-5-6. 1 Mapping File Pages To A Process - This use of the PMAP% call 
changes the map of the process so that references to pages in the 
process reference pages in a file. This does not actually cause data 
to be transferred; it simply changes the contents of the map. Later 
when changes are made to the actual page in the process, the changes 
will also be made to the page in the file, i f wr i te access has been 
specified for the file. 

Note that you cannot map file pages to pages in a process section that 
does not exist in the the process map. If you use PMAP% to input file 
pages to pages in a nonexistent section of a process, the monitor 
generates an illegal instruction trap. 

In addition, you can map one or more file sections (of 512 pages each) 
into a process. See Section 8.3-1 for details. 

The PMAP% call accepts three words of arguments in AC1 through AC3- 

AC1: JFN of the file in the left half, and the page number in 
the file in the right half 

AC2: process identifier (refer to Section 5«3) in the left 
half, and page number in the process in the right half 

AC3: repetition count and access 

The repetition count and access bits that can be specified in AC3 are 
described in Table 3~6. 
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| Table 3~6s PMAP% Access Bits 

I 
I 



Bit 



Symbol Meaning 



PM%CNT 



2 


PM%RD 


3 


PM%WR 


it 


PM%EX 



10 



11 



PM%PLD 



PM%CPY 



PM%EPN 



PM%ABT 



18-35 PM%RPT 



Repeat the mapping operation the number of 
times specified by the right half of AC3. The 
file page number and the process page number 
are incremented by 1 each time the operation 
is performed. 

Allow read access to the page. 

Allow write access to the page. 

Reserved. 

The symbol PM%RWX can be used to set B2-it. 

Preload page being mapped (move the page 
immediately instead of waiting until it is 
referenced) . 

Create a private copy of the page if the 
process writes into the page. This is called 
copy-on-wr i te and causes the map to be changed 
so that it identifies the copy instead of the 
original. Write access is allowed to the copy 
even if it was not allowed to the original. 
This allows a process to change a page of data 
without changing the data for other processes 
that have also mapped the page. 

Bits 18-35 of AC2 contain extended (l8-bit) 

process page number. If the section 

containing the page does not exist, a private 
section is created. 



Unmap page 
contents. 



and discard (abort) changed 



The number of times to repeat the 
operation if bit (PM%CNT) is set. 



mappi ng 
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With this use of the PMAP% call, the present contents of the page in 
the process are removed. If the page in the file is currently 
nonexistent, it will be created when it is written. 

This use of the PMAP% call is valid only if the file is opened for at 
least read access. If write access is requested in the PMAP% call, it 
is not granted unless it was also specified in the 0PENF% call when 
the file was opened. 

A file cannot be closed while any of its pages are mapped into any 
process. Thus, before a file is closed, its pages must be unmapped 
(refer to Section 3 -5 -6 . 3) • 

After execution of the PMAP% call, control returns to the user's 
program at the instruction following the call. If an error occurs, an 
illegal instruction trap is generated. 



3.5-6.2 Mapping Process Pages To A File - This use of the PMAP% call 
actually transfers data by moving the specified page in the process to 
the specified page in the file. The process map for the page is now 
empty. Both the page in the process and the page in the file must be 
private; that is, no other process can have the page mapped into its 
address space. The ownership of the process page is transferred to 
the file page. The previous contents of the page in the file are 
deleted. 

The three words of arguments are as follows: 

AC1: process identifier (refer to Section 5.3) in the left 
half, and page number in the process in the right half 

AC2: JFN of the file in the left half, and the page number in 
the file in the right half 

AC3: repetition count and access (refer to Section 3.5.6. 1) 

The access requested in the PMAP% call is granted only if it does not 
conflict with the access specified in the OPENFfc call when the file 
was opened. 

This use of the PMAP% call does not automatically update the files 
byte count and the byte size. To allow the file to be read later with 
sequential I/O monitor calls, the program should update the file's 
byte count and the byte size. (Refer to the CHFDB% monitor call in 
the TOPS-20 Monitor Cal Is Reference Manual) . 
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3.5.6.3 Unmapping Pages In A Process - As stated previously, a file 
cannot be closed if any of its pages are mapped in any process. To 
unmap a file's pages from a process, the program must execute the 
SMAP% call, or the following form of the PMAP% call: 

AC1: -1 

AC2: process identifier in the left half, and page number in 
the process in the right half. 

AC3: the repeat count for the number of pages to remove from 
the process (refer to Section 3-5-6.1) . 



3.5.7 Mapping File Sections to a Process 

A section of memory is a unit of 512 pages of process address space. 
File sections also contain 512 pages. The first page of each file 
section has a page number that is an integral multiple of 512. Like 
memory pages, sections can be mapped from one process to another, from 
a process to itself, or from a file to a process. Chapter 8 describes 
the SMAP% call completely. 

The SMAP% (Section Mapping) monitor call is similar to the PMAP% call. 
The SMAP% call maps one or more sections from a file to a process (for 
input), or from one process to another process. To map a process 
section to a file, you must use the PMAP% call as described in Chapter 
5 to map each page. 

Mapping a file section to a process section with SMAP% does not cause 
data to move from the disk to memory. Instead, SMAP% changes the 
contents of the process memory map so that the process section pointer 
points to a file section. The monitor transfers data only when your 
program references a memory page to which a file page is mapped. 
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To map a file section to a process section, SMAP% requires three 
arguments: 

AC1: source identifier: a JFN in the left half, and a file 
section number in the right half. If several contiguous 
sections are to be mapped, the number in the right half is 
that of the first section in the group of contiguous 
sections. 

AC2: destination identifier: process identifier in the left 
half, and a process section number in the right half. If 
several contiguous sections are to be mapped, the number 
in the right half is the number of the first section into 
which SMAP% maps a file section. 

AC3: flags that control access to the process section in the 

left half, and, in the right half, the number of sections 

to map into the process. The number of sections to map 
cannot be less than 1 nor more than 32 (decimal) . 

The flags in the left half of AC3 are described in Table 3-7. 
Table 3-7: SMAP% Access Bits 



Bit Symbol Meaning 



2 SM%RD Allow read access. 

3 SM%WR Allow write access. 

*t SM%EX Allow execute access. 

6 SM%IND Map the destination section using an indirect 

section pointer. 



3-32 



USING FILES 



3.6 CLOSING A FILE 

Once data has been transferred to or from a file, the user's program 
must close the file. When a file is closed, the system automatically 
performs the following: 

1. Updates the directory information for the file. For example, 
for a file to which sequential bytes had been written, the 
byte size and byte count are updated when the file is closed. 



Releases the JFN associated with the file. 



However , the 



user's program can request to close the file, but retain the 
JFN assignment. This is useful if the program plans to 
reopen the same file later, but does not want to execute 
another GTJFN% call. 



3.6.1 CL0SF% Monitor Call 

The CL0SF% (Close File) monitor call closes either the specified file 

or all files that are opened for the process executing the call. The 

CL0SF% call accepts one word of arguments in AC1 - flag bits in the 

left half and the JFN of the file to be closed in the right half. The 
flag bits are described in Table 3-8. 



Table 3~8: CL0SF% Flag Bits 



Bit 



Symbol Meaning 




6 



C0%NRJ 
CZ%ABT 



Do not release the JFN from the file. 

Abort any output operations currently being 
done. That is, close the file but do not 
perform normal cleanup operations (for example, 
do not output any data remaining in the 
buffers). If output to a new disk file that has 
not been closed is aborted, the file is closed 
and then deleted. 



CS%NUD 



Do not update the copy of the directory on 
disk (refer to the CHFDB% description in 
T0PS-20 Monitor Cal Is Reference Manual for 
information) . 



the 

the 

more 
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If the contents of AC1 is -1, all files that are opened for this 
process are closed. 

If the execution of the CL0SF% call is successful, the specified 
file is closed, and the JFN associated with the file is released if 
C0%NRJ was not set in the call. The execution of the user's program 
continues at the second location after the CL0SF% call. 

If the execution of the CL0SF% call is not successful, the file is 
not closed and an error code is returned in the right half of AC1. 
The execution of the user's program continues at the instruction 
following the CL0SF% call. 

The following sequence illustrates the closing of two files. 

CLOSIF: HRRZ 1.INJFN ;obtain input JFN 

CL0SF% ;close input file 

ERJMP FATAL ;if error, print message and stop 

CLOSOF: HRRZ 1.0UTJFN ;obtain output JFN 

CL0SF% jclose output file 

ERJMP FATAL ;if error, print message and stop 



3-7 ADDITIONAL FILE I/O MONITOR CALLS 



3.7.1 GTSTS% Monitor Call 

The GTSTS% (Get Status) monitor call obtains the status of a file. 
This call accepts one argument word - the JFN of the file in the 
right half of the AC1. The left half of AC1 is zero. 

Control always returns to the user's program at the instruction 
following the GTSTS% call. Upon return, appropriate bits reflecting 
the status of the specified JFN are set in AC2. These bits, and 
their meanings, are described in Table 3-9. Note that if the JFN is 
illegal or unassigned, bit 10 (GS%NAM) will not be set. 
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Table 3~9: Bits Returned on GTSTS% Call 



Bit Symbol 



Meaning 



GS%0PN 

1 GS%RDF 

2 GS%WRF 

.3 GS%XCF 

k GS%RND 

5-6 

7 GS%LNG 

8 GS%E0F 

9 GS%ERR 



GS%NAM 



1 1 GS%AST 



12 GS%ASG 



13 GS%HLT 



The file is open. If this bit is not 
set, the file is not open. 

If the file is open (for example, 
GS%0PN is set), it is open for read 
access. 

If the file is open, it is open for 
write access. 

File is open for execute access. 

If the file is open, it is open for 
non-append access (that is, its 
pointer can be reset). 

Reserved for Digital. 

File has pages in existence beyond 
page number 511- 

The last read operation to the file 
was at the end of the file. 

The file may be in error (for example, 
the bytes read may be erroneous) . 

A file specification is associated 
with this JFN. This bit will not be 
set if the JFN is in any way illegal. 

One or more fields of the file 
specification associated with this JFN 
contain a wildcard character. 

The JFN is currently being assigned 
(that is, a process other than the one 
executing the GTSTS call is assigning 
this JFN) . 

An I/O error is considered to be a 
terminating condition for this JFN. 
That is, the 0PENF% call for this JFN 
had bit 0F%HER set. 



3-35 



USING FILES 



Table 3~9: Bits Returned on GTSTS% Call (Cont.) 



Bit 



Symbol 



Meaning 



H-16 

17 GS%FRK 

18 GS%PLN 

19-31 

32-35 GS%M0D 



Reserved for Digital. 

Access to the file is restricted to 
only one process. 

If on, file line numbers are passed 
during input; if zero, line numbers 
are stripped before input. 

Reserved for Digital. 

The data mode of the file (refer to 
the 0PENF% call) . 

Value Symbol Meaning 

.GSNRM Normal (sequential) I/O 

1 .GSSMB Small buffer mode 
10 .GSIMG Image (binary) I/O 
17 .GSDMP Dump I/O 



An example of the GTSTS% call is shown in the first program in Section 
3-9. 



3-7-2 JFNS% Monitor Call 

The JFNS% (JFN to String) monitor call returns the file specification 
currently associated with the specified JFN. The call accepts three 
words of arguments in AC1 through AC3. 

AC1: destination designator where the file specification 
associated with the JFN is to be written. This 
specification is an ASCIZ string. 

AC2: JFN or pointer to string (see below) 

AC3: format to be used when returning the specification (see 
be 1 ow) 
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The contents of AC1 can be any valid destination designator (refer to 
Section 3-5«2) . 

The contents of AC2 can be one of two formats. The first format is a 
word with either flag bits or in the left half and the JFN in the 
right half. The bits that can be given in the left half of AC2 are 
the ones returned from the GTJFN% call (refer to Table 3-3). When the 
left half of AC2 is nonzero (that is, contains the bits returned from 
the GTJFN% call), the string returned will contain wildcard characters 
for appropriate fields and 0, -1, or -2 as a generation number if the 
corresponding bit is on in the JFNS% call. When the left half of AC2 
is 0, the string returned is the exact specification for the file (for 
example, wildcard characters are not returned for any fields). If the 
JFN is associated only with a file specification and not with an 
actual file (that is, bit GJ%0FG was set in the GTJFN% call), the 
string returned will contain null fields for unspecified fields and 
the actual values for specified fields. The second format allowed for 
AC2 is a pointer to the string in the program's address space that is 
to be returned upon execution of the call. Refer to the T0PS-20 
Moni tor Calls Reference Manual for the explanation of this format. 

The contents of AC3 specify the format in which the specification is 
written to the destination. Bits through 20 are divided into 3-bit 
bytes, each byte representing a field in the file specification. The 
value of the byte indicates the format for that field. The possible 
values are: 

Value Symbol Meaning 

.JSNOF Do not return this field when returning the 

file speci f ication. 

1 .JSAOF Always return this field when returning the 

file speci f ication. 

2 .JSSSD Suppress this field if it is the standard 

system value for this field (refer to Table 
3-D. 

If the contents of AC3 is zero, the file specification is written in 
the format 

dev:<di rectory>name. typ.gen;T 

with fields the same as the standard system value (see Table 3-1) not 
returned and protection and account fields returned only if bit 9 and 
bit 10 in AC2 are on, respectively. The temporary attribute (;T) is 
returned only if the file is temporary. 
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Table 3"10 describes the bits that can be set in AC3. 



Table 3-10: JFNS% Format Options 



Bit 



Symbol 



Meaning 



JS%N0D 

1-2 JS%DEV 

3-5 JS%DIR 

6-8 JS%NAM 

9-11 JS%TYP 

1 2-llt JS%GEN 

0-14 JS%SPC 



15-17 JS%PR0 
18-20 JS%ACT 
21 JS%TMP 



22 



23 



24 



JS%SIZ 



JS%CDR 



JS%LWR 



Print node name if node name is 
present. 

Format for device field. 

Format for directory field. 

Format for filename field. A value of 
2 (that is, bit 7 set) for this field 
is i 1 legal . 

Format for file type field. A value 
of 2 (that is, bit 10 set) for this 
field is i 1 legal . 

Format for generation number field. 

Output for all file specification 
fields named above. This field should 
have the same bits set as would be set 
in the fields above. (See B35 
(JS%PAF) below.) 

Format for protection field. 

Format for account field. 

Return temporary file indication ;T if 
the file specification is for a 
temporary file. 

Return size of file in pages (see 
below) . 

Return creation date of file (see 
below) . 

Return date of last write operation to 
file (see below) . 
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Table 3 ~ 1 : JFNS% Format Options (Cont.) 



Bit Symbol 



Meaning 



25 JS%LRD 

26 JSfcPTR 



| 27 


JS%ATR 


i 28 


JS%AT1 


[ 29 


JS%0FL 


I 30-31 




32 


JS%PSD 



33 



3*t 



35 



JS%TBR 



JS%TBP 



JS%PAF 



Return date of last read operation 
from file (see below). 

AC2 contains a pointer to the string 
containing the field to be returned 
(refer to the TOPS-20 Moni tor Cal Is 
Reference Manual for a description of 
this use of the JFNS% call). 

Return file specification attributes 
if appropriate. 

Return specification attribute 
referenced in kCk. 

Return the "OFF-LINE" attribute. 

Reserved for Digital. 

Punctuate the size and date fields 
(see below) in the file specification 
returned. 

Place a tab before all fields returned 
(that is, fields whose value is given 
as 1 in the 3-bit field) in the file 
specification, except for the first 
field. 

Place a tab before all fields that may 
be returned (that is, fields whose 
value is given as 1 or 2 in the 3 - bit 
field) in the file specification, 
except for the first field. 

Punctuate all fields (see below) 
returned in the file specification 
from the device field through the ;T 
field. 

If bits 32 through 35 are not set, no 
punctuation is used between the 
fields. 
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The punctuation used on each field is shown below. 

dev:<di rectory>name.typ.gen; A (account) ;P (protection) ;T (temporary) 
, size, creation date, write date, read date 

Refer to Section 1.2.2 for information on error returns. 



3.7.3 GNJFN% Monitor Call 

Occasionally a program may be written to perform similar operations on 
a group of files instead of only on one file. However, the program 
should not require the user to give a file specification for each 
file. Because the GTJFN% call associates a JFN with only one file at 
a time, the program needs a method of assigning a JFN to all the files 
in the group. By using the GTJFN% call to initially obtain the JFN 
and the GNJFN% call to assign the same JFN to each subsequent file in 
the group, a program can accept a specification for a group of files 
and process each file in the group individually. After the user gives 
the initial file specification, the program requires no additional 
i nput . 

Before an example showing the interaction of these two calls is given, 
a description of the GNJFN% (Get Next JFN) monitor call is 
appropr iate. 

The GNJFN% monitor call assigns a JFN to the next file in a group of 
files that have been specified with wildcard characters. The next 
file is determined by searching the directory in the order described 
in Section 3 - 3 • 1 • 1 using the current file as the first item. This 
call accepts one argument word in AC1 - the flags returned from the 
GTJFN% call in the left half and the JFN of the current file in the 
right half. In other words, the information returned in AC1 from the 
GTJFN% call is given as an argument to the GNJFN% call. Therefore, 
the program must save this information for use with the GNJFN% call. 

If execution of the GNJFN% call is successful, the same JFN is 
assigned to the next file in the group. The left half of AC1 contains 
various flags and the right half contains the JFN. The execution of 
the program continues at the second instruction after the GNJFN% call. 

I Table 3~11 describes the bits that can be returned in AC1 on a 
successful GNJFN% cal 1 . 
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| Table 3— lis GNJFN% Return Bits 

I 

I 



Bit Symbol 



Meani ng 



13 



14 



GN%STR 



GN%DIR 



15 GN%NAM 

16 GN%EXT 



A change in structure occurred between 
the previous file and this file. 

A change in directory occurred between 
the previous file and this file. 

A change in filename occurred between 
the previous file and this file. 

A change in file type occurred between 
the previous file and this file. If 
GN%NAM is on, this bit will also be on 
because the system considers two files 
with different filenames but with the 
same file type as a change in both the 
name and type. 



If execution of the GNJFN% call is not successful, an error code is 
returned in the right half of ACT. Conditions that can cause an error 
return are: 

1. The file currently associated with the JFN must be closed, 
and it is not. This means that the program must execute a 
CL0SF% call (with C0%NRJ set to retain the JFN) before 
executing a GNJFN% call. 

2. There are no more files in this group. This return occurs on 
the first GNJFN% call after all files in the group have been 
stepped through. The JFN is released when there are no more 
files. (Note: This error may occur if the file currently 
associated with the JFN is deleted or renamed.) 



The execution of the program continues at the next 
the GNJFN% call . 



instruction after 
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Consider the following situation. The user wants to write a program 
that will accept from his terminal a specification for a group of 
files and then perform an operation on each file individually without 
requiring additional input. Assume the user's directory <TRAIN> 
contains the following files: 

FIRST. MAC. 1 
FIRST. REL.l 
SECOND. REL.l 
THIRD.EXE. 1 

As discussed in Section 3-3-1.1, a group of files can be given to the 
GTJFN call by supplying a specification that contains wildcard 
characters in one or more of its fields. Thus, the specification 

<TRAIN>*.* 

would refer to all four files in the user's directory <TRAIN>. 

In his program, the user includes a GTJFN% call that will accept the 
above specification. 

The cal 1 is 

MOVX AC1 ,GJ%0LD+GJ%l FG+GJ%FLG+GJ%FNS+GJ%SHT 

MOVE AC2,[.PRI IN...PRI0U] 

GTJFN% 

and indicates that 

1. The file specification given must refer to an existing file 

(GJ%0LD) . 

2. The file specification given is allowed to contain wildcard 
characters (GJ%IFG). 

3. Flags will be returned in AC1 on a successful call (GJ%FLG) . 
The flags must be returned because they will be given to the 
GNJFN% call as arguments. 

k. The contents of AC2 will be interpreted as containing an 
input and output JFN (GJ%FNS) . 

5. The short form of the GTJFN% call is being used (GJ%SHT) . 

6. The file specification is to be read from the user's terminal 

(.PR I IN...PRI0U) . 

When the user types the specification <TRAIN>fc.* as input, the system 
associates the JFN with one file only. This file is the first one 
found when searching the directory in the order specified in Section 
3.3.I.I. Thus the JFN returned is associated with the file 
FIRST. MAC. 1. 

3-42 



USING FILES 



After the GTJFN% call is successfully executed, AC1 contains 

appropriate flags in the left half and the JFN assigned in the right 

half. The flags that wi 1 1 be returned in this particular situation 
are: 



GJ%NAM (bit 3) 
GJ%EXT (bit 4) 
GJ%GND (bit 12) 



A wildcard character appeared in the name 
field of the file specification given. 

A wildcard character appeared in the type 
field of the file specification given. 

Any files marked for deletion will not be 
considered. 



These flags inform the program of the fields t 
characters. The user's program must now 
because this word will be used as the argument 
The program then performs its desired oper 
Once its processing is completed, the prog 
specification of the next file. But ins 
specification from the user, the program execu 
obtain it. The argument to the GNJFN% cal 
returned from the previous GTJFN% call. Thus, 
is equivalent to: 

MOVE AC1 , [GJ%NAM+GJ%EXT+GJ%GND, , JFN] 
GNJFN% 



hat contained wildcard 
save the contents of AC1 
to the GNJFN% call, 
ation on the first file, 
ram is ready for the 
tead of requesting the 
tes the GNJFN% cal 1 to 
1 is the contents of AC1 
the cal 1 in thi s case 



Upon successful execution of the GNJFN% call, the JFN is now 
associated with the next file in the group (that is, F IRST.REL. 1) . 
AC1 contains appropriate flags in the left half and the same JFN in 
the right half. In this example, the flag returned is GN%EXT (bit 16) 
to indicate that the file type changed between the two files. 

After processing the second file, the user's program executes another 
GNJFN% call using the original contents of AC1 returned from the 
GTJFN% call. The original contents must be used because this word 
indicates the fields containing wildcard characters. If the current 
contents of AC1 (that is, the flags returned from the GNJFN% call) are 
used, a subsequent GNJFN% call would fail because there are no flags 
set indicating fields containing wildcard characters. This second 
GNJFN% call associates the JFN with the file SECOND. REL . 1 . The flags 
returned in AC1 are GN%NAM (bit 15) and GN%EXT (bit 16) indicating 
that the filename and file type changed between the two files. 
(Remember that a change in filename implies a change in file type even 
if the two file types are the same.) 
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After processing this third file, the user's program executes another 
GNJFN% call using the original contents of AC1. Upon execution of the 
call, the JFN is now associated with THIRD.EXE. 1, and the flags 
returned are GN%NAM and GN%EXT, indicating a change in the filename 
and file type. 

After processing the file THIRD.EXE. 1, the user's program executes a 
final GNJFN% call. Since there are no more files in the group, the 
call returns an error code and releases the JFN. Execution of the 
user's program continues at the instruction following the GNJFN% call. 



3.8 SUMMARY 

To read from or write to a file, the user's program must: 

1. Obtain a JFN on the file with the GTJFN% monitor call (refer 
to Section 3 - 3 - • 

2. Open the file with the 0PENF% monitor call (refer to Section 
3.^.1). 

3. Transfer the data with byte, string, or page I/O monitor 
calls (refer to Section 3-5) • 

h. Close the file with the CL0SF% monitor call (refer to Section 
3.6.1) . 
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3-9 FILE EXAMPLES 

Example 1 - This program assigns JFNs, opens an input file and an 
output file, and copies data from the input file to the output file. 
Data is copied until the end of the input file is reached. Refer to 
the TO PS-20 Monitor Cal Is Reference Manual for explanation of the 
ERSTR% monitor cal 1 . 

J*** PROGRAM TO COPY INPUT FILE TO OUTPUT FILE. *** 
i (USING BINX/BOUTX AND IGNORING NULLS) 

TITLE FILE 10 5 TITLE OF PROGRAM 

search monsym ', search system jsys-symbol library 
search macsym 
.require sysimacrel 

**** impure data storage and definitions *** 

injfnj block 1. s storage for input jfn 

outjfn: block i ; storage for output jfn 

pdlen==3 p stack has length 3 

pdlst5 block pdlen pset aside storage for stack 

stdac. jdefine standard acs, see macsym. 

?*** program initilization **# 

start? resets ? close files* etc. 

MOVE PvCIOWD PDLEN fPDLST::I ^ESTABLISH STACK 

P*** GET INPUT FILE *** 

INF' 1 1.: J PROMPT FOR INPUT FILE 

TMSG < 

input file! > jon controlling terminal 

movx ti»gj%old+gj%fns+gj%sht } search modes for gtjfn 

^existing file only» file-nrs in b 
? short call 
move t2»r..priinff .pri0u.i pgtjfn's i/o with controlling term 
gtjfnz sget job file number (jfn) 

erjmps i push j pi. warn p if error , give warning 
jrst :i:nfii...::i pand let him try again 

MOVEM TIjINJFN f SUCCESS r SAVE THE JFN 

P*** GET OUTPUT FILE *** 

OUTFILJ SPRINT PROMPT FOR 

TMSG < 
OUTPUT FILE! > f OUTPUT FILE 

MOVX Tl»GJXFOU+GJXMSG+GJZCFM+GJZFNS+GJZSHT SGTJFN SEARCH MODES 

5 [DEFAULT TO NEW GENERATION* PRINT 
P MESSAGE r REQUIRE CONFIRMATION 
5 FILE-NR'S IN T2, SHORT CALL 1 
MOVE T2»r..PRIIN»p.PRI0U3 PI/O WITH CONTROLLING TERMINAL 
GTJFN% 5 GET JOB FILE NUMBER 

ERJMPS C PUSHJ P » WARN PIF ERROR? GIVE WARNING 
JRST OUTFIL3 PAND LET HIM TRY AGAIN 
MOVEM Tl» OUTJFN PSAVE THE JFN 
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SNOWf OPEN THE FILES WE JUST GOT 
f INPUT 

MOVE TIfINJFN fRETRIEVE THE INPUT JFN 

MOVX T2»FLD(7»0FXBSZ)+0FZRD t MODES FOR OPENF E7-BIT BYTES + INPUT] 
OF'FNFZ fOPEN THE FILE 

ERJMPS FATAL fIF ERROR? GIVE MESSAGE AND STOP 



OUTPUT 



MOVE TIfOUTJFN 5 GET THE OUTPUT JFN 

MOVX T2fFLD(7f0F7.BSZ)+0F%WR (MODES FOR OPENF C 7-BIT BYTES + OUTPUT] 
OPENF% 50PEN THE FILE 

ERJMPS FATAL J IF ERROR , GIVE MESSAGE AND STOP 



f*** MAIN LOOP: COPY BYTES FROM INPUT TO OUTPUT *** 
LOOP 



MOVE TIfINJFN 

BIN* 

JUMPE TI'fDONE 

MOVE TIfOUTJFN 

BOUT 

ERCALS ERROR 
JRST LOOP 



fGET THE INPUT JFN 

STAKE A BYTE FROM THE SOURCE 

fIF Of CHECK FOR END OF FILE 

fGET THE OUTPUT JFN 

5 OUTPUT THE BYTE TO DESTINATION 

J LOOP f STOP ONLY ON A BYTE 
f (FOUND AT LOOP+2) 



,*** TEST FOR END OF FILEf ON SUCCESS FINISH UP *** 

done: 



GTSTSX 

TXNN T2fGS%E0F 

JRST LOOP 



closif: move tifInjfn 

CLOSFZ 
ERJMPS FATAL 

CLOSOF: MOVE TIfOUTJFN 

CLOSFX 
ERJMPS FATAL 

TMSG < 
[DONE 3 > 

JRST ZAP 



fGET THE STATUS OF INPUT FILE 

J AT END OF FILE? 

fNCIf FLUSH NULL AND CONTINUE COPY 

fYESf RETRIEVE INPUT JFN 

f CLOSE INPUT FILE 

8 IF ERROR f GIVE MESSAGE AND STOP 

f PETRI EVE OUTPUT JFN 

f CLOSE OUTPUT FILE 

fIF ERROR f GIVE MESSAGE AND STOP 

f SUCCESSFULLY DONE 
fSTOP 



f*** ERROR HANDLING *** 
TMSO < 



fatal: 



PUSH J Pf ERROR 
JRST ZAP 



J FATAL ERRORS PRINT ? FIRST 
fTHEN PRINT ERROR MESSAGE 
?AND STOP 



WARN ! 
%> 



ERROR! 



ZAP! 



TMSG 



MOVE I TIf .PRIOU 

MOVE T2fC.FHSL.Ff y-ll 

SETZ T3f 

ERSTRZ 

JFCL 

JFCL 
POP J Pf 

HALTFZ 
JRST START 
END START 



5 WARNINGS PRINT % FIRST 

HAND FALL THRU 'ERROR' BACK TO CALLER 

f D E C L. A R E PRINCIPAL OUTPUT DEVICE 

fFOR ERROR MESSAGE 

% C U R R E N T F R K f f L A S T E R R R 

fNO LIMITff FULL MESSAGE 

f PRINT THE MESSAGE 

i IGNORE UNDEFINED ERROR NUMBER 

P IGNORE ERROR DURING EXE OF ERSTR 

f RETURN TO CALLER 

.STOP 

5 WE ARE RESTARTABLE 

5 TELL LINKING LOADER START ADDRESS 
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Example 2 - This program accepts input from a user at the terminal and 
then outputs the data to the line printer. Refer to Section 2.9 for 
explanation of the RDTTY% call. 

TITLE LPTPNT $ PROGRAM TO PRINT TERMINAL. INPUT ON PRINTER 

SEARCH MONSYM i SEARCH SYSTEM JSYS ■SYMBOL LIBRARY 

SEARCH MACSYM 
.REQUIRE SYSJMACREI... 

STB AC, v DEFINE STANDARD ACs 

BUFSIZ"— 200 
PHLEN-S--50 

COUNT! BLOCK I 

LPT J ENS BLOCK i 

BUFFER! BLOCK BUFSIZ 

PDL! BLOCK PDLEN 

START! RE SET % 5 RESET I/O. ETC, 

MOVE P.LIOWD PDLEN » PHI. 3 5 BET UP STACK 
TMSG <ENTER TEXT TO BE PRINTED (END WITH "Z)J 

> .OUTPUT PROMPTING TEXT 
HRROI Tl . BUFFER 5 GET POINTER TO BUFFER 

MOVE T2»ERDZBRK+BUFSIZ*5::i (GET FLAG AND MAX # OF CHARS TO READ 

SETZM T3 PNO RE ■TYPE BUFFER 

RDTTYX 5 INPUT TEXT FROM TERMINAL 

EJSHLT i ERROR . STOP 

HRRZS T2 j GET CHARS REMAINING IN BUFFER 

MOVEI T1»BUFSIZ*S i COMPUTE NUMBER OF CHARS READ =• BUFFERSIZE 

SUB T1.T2 5 MINUS CHARS REMAINING 

SOS Ti 5 DON'T INCLUDE "Z 

MOVEM Tl. COUNT J SAVE * OF CHARS INPUT 

5 GET A J FN FOR THE PRINTER AND OPEN THE PRINTER 

MOVX T1.BJST.SHT! (3 JXFOU i OUTPUT FILE. SHORT CALL 

HRROI T2.EA8CIZ /LPTJ/3 5GET POINTER TO NAME OF FILE 

GTJFN/J vGET A JFN FOR THE PRINTER 

ERJMPS JFNERR 5 ERROR. PRINT ERROR MESSAGE 

MOVEM Tl. LPT JFN J REMEMBER PRINTER JFN 

MOVX T2.FLD<7.0FZBSZ)+0FZWR J7--BIT BYTES. WRITE ACCESS WANTED 

OPENF% JOPEN THE PRINTER FOR OUTPUT 

ERJMPS OPNERR 5 ERROR. PRINT ERROR MESSAGE 

SNOW OUTPUT THE TEXT THAT WAS INPUT FROM THE TERMINAL 

HRROI T2. BUFFER .GET POINTER TO TEXT (PRINTER JFN STILL IN Tl) 

MOVN T3» COUNT J GET NUMBER OF CHARS TCI OUTPUT 

SOUTX 5 OUTPUT STRING OF CHARS TO THE PRINTER 

ERJMPS DATERR i ERROR. PRINT ERROR MESSAGE 
TMSG < 
OUTPUT HAS BEEN SENT TO THE PRINTER,,, 

> 50UTPUT CONFIRMATION MESSAGE 
MOVE Tl.LPTJFN t GET PRINTER JFN 

CLOSF/i 5 CLOSE IT 

ERJMPS DATERR 5 UNEXPECTED ERROR. PRINT ERROR MESSAGE 

HALTFZ i FINISHED 

JRST START fIF CONTINUED. GO BACK TO START 
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4.1 OVERVIEW 

Program execution usually occurs in a sequential manner, where 
instructions are executed one after another. But sometimes a program 
must be able to receive asynchronous signals from terminals, the 
monitor, or other programs, or as a result of its own execution. By 
using the software interrupt system, the user can specify conditions 
that will cause his program to deviate from its sequential method of 
execution. 

An interrupt is defined as a break in the normal flow of control 
during a program's execution. The break, or interrupt, is caused by 
the occurrence of a prespecified condition. By specifying the 
conditions that can cause an interrupt, the program has the capability 
of dynamically responding to external events and error conditions and 
of generating requests for services. Because the program can respond 
to special conditions as they occur, it does not have to explicitly 
and repeatedly test for them. In addition, the program's execution is 
faster because the program does not have to include a special test 
after the possible occurrence of the condition. 

When an interrupt occurs, the system transfers control from the main 
program sequence to a previously-specified routine that will process 
the interrupt. After the routine has completed its processing of the 
interrupt, the system can transfer control back to the program at the 
point it was interrupted, and execution can continue. See Figure 4-1. 
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User 
Program 
Is 
Executing 



Interrupt 

Condition 

Occurs 



Has^ 

Program" 

Enabled for 

^Condition on This^, 

Channel? _ 



Yes 



Perform System 
Default Action 
(e.g., stop Job, 
print message) 



Is an 

'Interrupt of" 

Higher Priority 

Being 
J>rocessed?> 



Yes 



Execute 
User's 
Interrupt 
Routine 



Walt Until 
Higher Priority 
Interrupt 
Finishes 



User Program 
Continues if Job 
Has Not Been 
Terminated 



MR-S-2027-82 



Figure !*■— 1 s Basic Operational Sequence of the Software Interrupt 
System 
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4.2 INTERRUPT CONDITIONS 

Conditions that cause the program to be interrupted when the interrupt 
system is enabled are: 



1 



Conditions generated when specific terminal keys are typed. 
There are 36 possible codes; each one specifies the 
particular terminal character or condition on which an 
interrupt is to be initiated. Refer to Table 4-2 for the 
possible codes. 

Invalid instructions (for example, I/O instructions given in 
user mode) or privileged monitor calls issued by a non 
pr ivi leged user. 

Memory conditions, such as illegal memory references. 

Arithmetic processor conditions, such as arithmetic overflow 
or underflow. 

Certain file or device conditions, such as end of file. 

Program-generated software interrupts. 

Termination of an inferior process. 

System resource unavailability. 

Interprocess communication (IPCF) and Enqueue/Dequeue 
i nterrupts. 
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If. 3 SOFTWARE INTERRUPT CHANNELS AND PRIORITIES 

Each condition is associated with one of 36 software interrupt 
channels. Most conditions are permanently assigned to specific 
channels; however, the user's program can associate some conditions 
(for example, conditions generated by specific terminal keys) to any 
one of the assignable channels. (Refer to Table lt-1 for the channel 
assignments.) When the condition associated with a channel occurs, and 
that channel has been activated, an interrupt is generated. Control 
can then be transferred to the routine responsible for processing 
interrupts on that channel. 

The user program assigns each channel to one of three priority levels. 
Priority levels allow the occurrence of some conditions to suspend the 
processing of other conditions. The levels are referred to as level 
1, 2, or 3 with level 1 having the highest priority. Level is not a 
legal priority level. 1 



If an interrupt is generated in a process where the priority 
level is 0, the system considers that the process is not 
prepared to handle the interrupt. The process is then suspended 
or terminated according to the setting of bit 17 (SC%FRZ) in its 
capabi 1 i ty word. 
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Table 4-1: Software Interrupt Channel Assignments 



Channel 



Symbol 



Meani ng 



0-5 






6 




•ICAOV 


7 




. ICFOV 


8 






9 




. ICPOV 


10 




.ICEOF 


11 




. ICDAE 


12 




. 1 CQTA 


13- 


14 




15 




.ICILI 


16 




. ICIRD 


17 




. 1 C 1 WR 


18 






19 




•ICIFT 


20 




.ICMSE 


21 






22 




.ICNXP 


23- 


35 





Assignable by user program 

Arithmetic overflow 

Arithmetic floating point overflow 

Reserved for Digital 

Pushdown list (PDL) overflow 1 

End of file condition 

Data error file condition 1 

Disk quota exceeded 

Reserved for Digital 

I 1 legal i nstruction 1 

Illegal memory read 1 

I 1 1 ega 1 memory wr i te 1 

Reserved for Digital 

Inferior process termination 

System resources exhausted ! 

Reserved for Digital 

Nonexistent page reference 

Assignable by user program 



1 These channels (called panic channels) cannot be completely 
deactivated. An interrupt generated on one of these channels 
terminates the process if the channel is not activated. 
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The software interrupt system processes interrupts 
channels only, and each channel can be activated a 
independently of other channels. When activated, the 
generate an interrupt for its associated priority level, 
for any priority level is initiated only if there are no 
progress for the same or higher priority levels. If 
system remembers the interrupt request and initiates 
equal or higher priority level interrupts finish. Thi 
higher priority level request can suspend a routine proc 
level interrupt. Thus, the user must be concerned with 
when he assigns his priority levels. He must consider 
interrupt request can suspend the processing of anoth 
the processing of a second interrupt cannot be deferr 
completion of the first. See Figure if-2. 



on activated 

nd deactivated 

channel can 

An interrupt 

interrupts in 
there are, the 
it after all 
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Execution 
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Interrupt 

Routine 



Interrupt on 
Channel 6 
that Has a 
Priority Level 
of 2 



Channel 4 

Interrupt 

Routine 



Waiting 



Interrupt on 
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that Has a 
Priority Level 
oM 



Channel 6 Interrupt 
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Waiting 



Waiting 



Channel 4 

Interrupt 
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Routine 
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Completes 



User Program 
Continues 



Channel 35 

Interrupt 

Completes 



Figure k-2: Channels and Priority Levels 
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k.k SOFTWARE INTERRUPT TABLES 

To process interrupts, the user includes, as part of his program, 
special service routines for the channels he will be using. He must 
then specify the addresses of these routines to the system by setting 
up a channel table. In addition, the user must also include a 



priority level table as part of his program, 
the addresses of these tables to the system. 



Finally, he must declare 



^4.4.1 Specifying the Software Interrupt Tables 

Before using the software interrupt system, the user's program must 
set up the contents of the channel table and the priority level table. 
The program must then specify their addresses with either the SIR% or 
XSI R% moni tor cal 1 s. 

These calls are similar, but their differences are important. The 
SIR% call can be used in single-section programs, but the XSIR% call 
must be used in programs that use more than one section of memory. 
The SIR% call works in non-zero sections only if the tables are in the 
same section as the code that makes the call. The code that causes 
the interrupt must also be in that section, as must the code that 
processes the interrupt. Because of the limitations of the SIR% call, 
you should use the XS I R% call. 

The SIR% monitor call accepts two words of arguments: the identifier 
for the program (or process) in AC1, and the table addresses in AC2. 
Refer to Section 5-3 for the description of process identifiers. 

The following example shows the use of the S I R% call. 



MOVE I 1..FHSLF 

MOVE 2,[LEVTAB,,CHNTAB] 

S I R% 



identifier of current process 
;addresses of the tables 



The XSIR% call accepts the following arguments: in AC1, the 
identifier of the process for which the interrupt channel tables are 
to be set; in AC2, the address of the argument block. 



The argument block is 
format: 



a three-word block that has the following 



Length of the argument block, including this word 



Address of the interrupt level table 
Address of the channel table 
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Control always returns to the user's program at the instruction 
following the S I R% and XS I R% calls. If the call is successful, the 
table addresses are stored in the monitor. If the call is not 
successful, an illegal instruction trap is generated. 

Any changes made to the contents of the tables after the XSIR% or SIR% 
calls have been executed will be in effect at the time of the next 
i nterrupt. 



k.h.2 Channel Table 

The channel table, CHNTAB, 2 contains a one-word entry for each 
channel; thus, the table has 36 entries. Each entry corresponds to a 
particular channel, and each channel is associated at any given time 
with only one interrupt condition. (Refer to Table k-] for the 
interrupt conditions associated with each channel.) 

The CHNTAB table is indexed by the channel number (0 through 35). The 
general format, for use with the XS I R% and XRIR% monitor calls, can be 
used in any section of memory. The left half of each entry contains 
the priority level (1, 2, or 3) in bits 0-5 (SI%LEV) to which the 
channel is assigned. Bits 6-35 (SI%ADR) of each entry contain the 
starting address of the routine to process interrupts generated on 
that channel. If a particular channel is not used, the corresponding 
entry in the channel table should be zero. 

In the older format, for use with the SIR% and RIR% calls by any 
single-section program, the left half of each word contains the 
priority level (1, 2, or 3) for that channel. The right half contains 
the address of the interrupt routine that will handle interrupts on 
that channel . 



The user can call his priority channel table any name 
desires; however, it is good practice to call it CHNTAB. 
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;channel 





jchannel 


1 


;channel 


2 


jchannel 


3 


;channel 


k 


;channel 


5 


jchannel 


6 


jchannel 


7 


jchannel 


8 


jchannel 


9 


jchannel 


10 
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| The following example is for use with the XS I R% monitor call. 

I 

| CHNTAB: FLD (2,S I %LEV)+FLD (CHNOSV.S l%ADR) 

I FLD(2,SI%LEV)+FLD(CHN1SV,SI%ADR) 

J FLD(2,SI%LEV)+FLD(CHN2SV,SI%ADR) 

I FLD(2,SI%LEV)+FLD(CHN3SV,SI%ADR) 

I o 

I o 

I FLD(l,SI%LEV)+FLD(APRSRV,SI%ADR) 

i o 

I o 

I FLD(1,SI%LEV)+FLD(STKSRV,SI%ADR) 

I 



I jchannel 35 

| In this example, channels through 3 are assigned to priority level 

j 2, with the interrupt routine at CHNOSV servicing channel 0, the 

j routine at CHN1SV servicing channel 1, the routine at CHN2SV servicing 

j channel 2, and the routine at CHN3SV servicing channel 3. Channels 6 

i and 9 are assigned to priority level 1, with the routine at APRSRV 

I servicing channel 6 and the routine at STKSRV servicing channel 9. 

| All remaining channels are not assigned. 



j k. k. 3 Priority Level Table 
i 

| The priority level table, LEVTAB, 3 j s a three-word table, containing 

| a one-word entry for each of the three priority levels. In the 

| general form, each word contains the 30-bit address of the first word 

| of the two-word block in the process address space. The block 

| addressed by word n of LEVTAB is used to store the global PC flags and 

| address when an interrupt of level n+1 occurs. 
I 

| The PC flags are stored in the first word of the PC block, and the PC 

| address is stored in the second. This form of the table must be used 

j with the XSIR% and XR I R% monitor calls, and can be used in any 
section. 



The user can call his priority level table any name he desires; 
however, it is good practice to call it LEVTAB. 
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The older form of the interrupt level table can be used in any 
single-section program, and must be used with the SIR% and RIR% calls. 
This table also contains three words, indexed by the priority level 
minus 1. Each word contains zero in the left half, and the 18-bit 
address of the word in which to store the one-word section-relative PC 
in the right half. This address is assumed to be in the same program 
section that contained the SIR% monitor call. (For more information 
see Chapter 8.) The system must save the value of the program counter 
so that it can return control at the appropriate point in the program 
once the interrupt routine has completed processing an interrupt. If 
a particular priority level is not used, its corresponding entry in 
the level table should be zero. 

The following is a sample of a level table. 

LEVTAB: 0,,PCLEV1 ;Addresses to save PC for interrupts 

0,,PCLEV2 {occurring on priority levels 1 and 2. 
0,,0 :No priority level 3 interrupts are 

{planned 



4.5 ENABLING THE SOFTWARE INTERRUPT SYSTEM 

Once the interrupt tables have been set up and their addresses defined 
with the XS I R% monitor call, the user's program must enable the 
interrupt system. When the interrupt system is enabled, interrupts 
that occur on activated channels are processed by the user's interrupt 
routines. When the interrupt system is disabled, the monitor 
processes interrupts as if the channels for these interrupts were not 
activated. 

The E I R% monitor call, used to enable the system, accepts one 
argument: the identifier for the process in AC1. 

MOVE I 1..FHSLF ; identifier of current process 

E I R% 

Control always returns to the instruction following the EIR call. 



4.6 ACTIVATING INTERRUPT CHANNELS 

Once the software interrupt system is enabled, the channels on which 
interrupts can occur must be activated (refer to Table 4-1 for the 
channel assignments). The channels to be activated have a nonzero 
entry in the appropriate word in the channel table. 

The A I C% monitor call activates one or more of the 36 interrupt 
channels. This call accepts two words of arguments - the identifier 
for the process in AC1, and the channels to be activated in AC2 . 
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The channels are indicated by setting bits in AC2. Setting bit n 
indicates that channel n is to be activated. The AIC% call activates 
only those channels for which bits are set. 

MOVE I 1..FHSLF identifier of current process 

MOVE 2, [1B<. ICA0V>+1B<.ICP0V>] {activate channels 6 and 9 
Al C% 

Control always returns to the instruction following the AIC% call. 

Some channels, called panic channels, cannot be deactivated by 
disabling the channel or the entire interrupt system. (Refer to Table 
4-1 for these channels.) This is because the occurrence of the 
conditions associated with these channels cannot be completely ignored 
by the moni tor . 

If one of these conditions occurs, an interrupt is generated whether 
the channel is activated or not. If the channel is not activated, the 
process is terminated, and usually a message is output before control 
returns to the monitor. If the channel is activated, control is given 
to the user's interrupt routine for that channel. 



4.7 GENERATING AN INTERRUPT 

A process generates an interrupt by producing a condition for which an 
interrupt channel is enabled, such as arithmetic overflow, or by using 
the I I C% monitor call. This call can generate an interrupt on any of 
the 36 interrupt channels of the process the calling process 
specifies. See Section 5.10 for a description of the I I C% call. 



4.8 PROCESSING AN INTERRUPT 

When a software interrupt occurs on a given priority level, the 
monitor stores the current program counter (PC) word in the address 
indicated in the priority level table (refer to Section 4.4.3) • The 
monitor then transfers control to the interrupt routine associated 
with the channel on which the interrupt occurred. The address of this 
routine is specified in the channel table (refer to Section 4.4.2). 

Since the user's program cannot determine when an interrupt will 
occur, the interrupt routine must preserve the state of the program so 
the program can be resumed properly. First, the routine stores the 
contents of any user accumulators for use while processing the 
interrupt. After the accumulators are saved, the interrupt routine 
processes the interrupt. 
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Occasionally, an interrupt routine may need to alter locations in the 
main section of the program. For example, a routine may change the 
stored PC word to resume execution at a location different from where 
the interrupt occurred. Or it may alter a value that caused the 
interrupt. It is important that care be used when writing routines 
that alter data because any changes will remain when control is 
returned to the main program. For example, if data is inadvertently 
stored in the PC word, return to the main section of the program would 
be incorrect when the system attempted to use the word as the value of 
the program counter. 

If a higher-priority interrupt occurs during the execution of an 
interrupt routine, the execution of the lower-priority routine is 
suspended. The value of its program counter is stored at the location 
indicated in the priority level table for the new interrupt. When the 
routine for this new interrupt is completed, the suspended routine 
resumes. 

If an interrupt of the same or lower priority occurs during the 
execution of a routine, the monitor holds the interrupt until all 
higher or equal level interrupts have been processed. 

The system considers the user's program unable to process an interrupt 
on an activated channel if any of the following is true: 

1. The priority level associated with the channel is 0. 

2. The program has not defined its interrupt tables by executing 
an XS I R% or SIR% monitor call. 

3. The process has not enabled the interrupt system by executing 
an EIR% monitor call, and the channel on which the interrupt 
occurs is a panic channel. 

In any of these cases, an interrupt on a panic channel terminates the 
user's program. All other interrupts are ignored. 



^4.8.1 Dismissing An Interrupt 

Once the processing of an interrupt is complete, the interrupt routine 
should restore the user accumulators to their initial values. Then it 
should return control to the interrupted code by using the DEBRK% 
monitor call. This call restores the PC word and resumes the program. 
The call has no arguments, and must be the last statement in the 
interrupt routine. 
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If the interrupt-processing routine has not changed the PC of the 
user's program, the DEBRK% call restores the program to the same state 
the program was in just before the interrupt occurred. If the program 
was interrupted while waiting for I/O to complete, for example, the 
program will again be waiting for I/O to complete when it resumes 
execution after the DEBRK% call. 

If the PC word was changed, the program resumes execution at the new 
PC location. The state of the program is unchanged. 



4.9 TERMINAL INTERRUPTS 

The user's program can associate channels through 5 and channels 2k 
through 35 with occurrences of various conditions, such as the 
occurrence of a particular character typed at the terminal or the 
receipt of an IPCF message. This section discusses terminal 
interrupts; refer to Chapters 6 and 7 for other types of assignable 
interrupts. 

There are 36 codes used to specify terminal characters or conditions 
on which interrupts can be initiated. These codes, along with their 
associated conditions, are shown in Table k-2. 
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Table 4-2: Terminal Codes and Conditions 



Code Symbol Character or Condition 






.TICBK 


1 


.TICCA 


2 


.TICCB 


3 


.TICCC 


h 


.TICCD 


5 


.TICCE 


6 


.TICCF 


7 


.TICCG 


8 


.TICCH 


9 


.TICCI 


10 


.TICCJ 


1 1 


•TICCK 


12 


.TICCL 


13 


.TICCM 


H 


.TICCN 


15 


.TICCO 


16 


.TICCP 


17 


.TICCQ 


18 


.TICCR 


19 


.Tl CCS 



CTRL/@ or break 

CTRL/A 

CTRL/B 

CTRL/C 

CTRL/D 

CTRL/E 

CTRL/F 

CTRL/G 

CTRL/H 

CTRL/ I 

CTRL/J 

CTRL/K 

CTRL/L 

CTRL/M 

CTRL/N 

CTRL/0 

CTRL/P 

CTRL/Q 

CTRL/R 

CTRL/S 
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Table k-2: Terminal Codes and Conditions (Cont.) 

Code Symbol Character or Condition 

CTRL/T 

CTRL/U 

CTRL/V 

CTRL/W 

CTRL/X 

CTRL/Y 

CTRL/Z 

ESC key 

Delete (or rubout) key 

Space 

Dataset carrier off 

Typei n 

Typeout 

Two-character escape sequence 

Reserved 



20 


.TICCT 


21 


.TICCU 


22 


•TICCV 


23 


.TICCW 


2h 


.TICCX 


25 


.TICCY 


26 


.TICCZ 


27 


.TICES 


28 


.TICRB 


29 


.TICSP 


30 


.TICRF 


31 


.TICTI 


32 


.TICTO 


33 


.TITCE 


3^-35 
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To cause terminal interrupts to be generated, the user's program must 
assign the desired terminal code to one of the assignable channels. 
The ATI* monitor call is used to assign this code. This call accepts 
one word of arguments: the terminal code in the left half of AC1 and 
the channel number in the right half. 

MOVE 1,[.TICCE,,INTCH1] {assign CTRL/E to channel INTCH1 
ATI* 

Control always returns to the instruction following the ATI* call. If 
the current job is not attached to a terminal (there is no terminal 
controlling the job), the terminal code assignments are remembered; 
they will be in effect when a terminal is attached. 

The monitor handles the receipt of a terminal interrupt character in 
either immediate mode or deferred mode. In immediate mode, the 
terminal character causes the system to initiate an interrupt as soon 
as the user types the character (that is, as soon as the system 
receives it). In deferred mode, the terminal character is placed in 
either immediate mode or deferred mode. In immediate mode, the 
terminal character causes the system to initiate an interrupt as soon 
as the user types the character (as soon as the system receives it). 
In deferred mode, the terminal character is placed in the input stream 
in sequence with other characters of the input, unless two of the same 
character are typed in succession. In this case, an interrupt occurs 
at the time the second one is typed. If only one character enabled in 
deferred mode is typed, the system initiates an interrupt only when 
the program attempts to read the character. Deferred mode allows 
interrupt actions to occur in sequence with other actions specified in 
the input (for example, when characters are typed ahead of the time 
that the program actually requests them). In either mode, the 
character is not passed to the program as data. The system assumes 
that interrupts are to be handled immediately unless a program has 
issued the STIW* (Set Terminal Interrupt Word) monitor call. (Refer 
to TOPS-20 Monitor Cal Is Reference Manual for a description of this 
call.) 
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4.10 ADDITIONAL SOFTWARE INTERRUPT MONITOR CALLS 

Additional monitor calls are available that allow the user's program 
to check and to clear various parts of the software interrupt system. 
Also, there is a call useful for interprocess communication (refer to 
the IIC% call in Section 5.10). 



4.10.1 Testing for Enablement 

The SKPIR% monitor call tests the software interrupt system to see if 
it is enabled. The call accepts in AC1 the identifier of the process. 
After execution of the call, control returns to the next instruction 
if the system is off, and to the second instruction if the system is 



on. 



MOVE I 1..FHSLF ;identifier of current process 

SKPIR% ;test interrupt system 

return jsystem is off 

return jsystem is on 



4.10.2 Obtaining Interrupt Table Addresses 

The R I R% and XRIR% monitor calls obtain the channel and priority level 
table addresses for a process. These calls are useful when several 
routines in one process want to share the interrupt tables. 



4.10.2.1 The R I R% Monitor Call - The RIR% monitor call can be used in 
any section of memory, but is only useful for obtaining table 
addresses if those tables are in the same section of memory as the 
code that makes the call. Furthermore, it can only obtain table 
addresses that have been set by the SIR call. 

The call accepts the identifier of the process in AC1. It returns the 
table addresses in AC2. The left half of AC2 contains the 
section-relative address of the priority level table, and the right 
half contains the section-relative address of the channel table. If 
the process has not set the table addresses with the SIR% monitor 
call, AC2 contains zero. 

Control always returns to the instruction following the RIR% call. 

The following example shows the use of the R I R% call. 

M0VEI 1..FHSLF {identifier of current process 

R I R% ;return the table addresses 
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4.10.2.2 The XRIR% Monitor Call - This call obtains the addresses of 
the interrupt tables defined for a process. The tables can be in any 
section of memory. The code that makes the call can also be in any 
section. This call can only obtain addresses that have been set by 
the XSIR% call . 

The call accepts the identifier of the process in AC1, and the address 
of the argument block in AC2. The argument block is three words long, 
word zero must contain the number 3. The call returns the addresses 
into words one and two. The block has the following format: 



! Length of the argument block, including this word ! 
Address of the interrupt level table 
Address of the channel table 



Control always returns to the instruction following the XRIR% call. 
If the process has not set the table addresses with the XS I R% monitor 
call, words one and two of the argument block contain zero. 



4.10.3 Disabling the Interrupt System 

The DIR% monitor call disables the software interrupt system for the 
process. It accepts the identifier of the process in AC1. 



MOVEI 1..FHSLF 
DIR% 



; identifier of current process 
;disable system 



Control always returns to the instruction following the DIR% call. 

If interrupts occur while the interrupt system is disabled, they are 
remembered until the system is reenabled. At that time, the 
interrupts take effect unless an intervening C I S% monitor call (refer 
to Section 4.10.6) has been issued. 

Software interrupts assigned to panic channels are not completely 
disabled by the D I R% call. These interrupts terminate the process, 
and the superior process is notified if it has enabled channel .ICIFT. 
In addition, if the terminal code for CTRL/C (.TICCC) is assigned to a 
channel, it causes an interrupt that cannot be disabled by the D I R% 
call. However, the CTRL/C interrupt can be disabled by deactivating 
the channel assigned to the CTRL/C terminal code. 
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4.10.4 Deactivating a Channel 

The DIC% monitor call is used to deactivate interrupt channels. The 
call accepts two words of arguments: the process identifier in AC1, 
and the channels to be deactivated in AC2. Setting bit n in AC2 
indicates that channel n is to be deactivated. 

MOVE I 1..FHSLF identifier of current process 

MOVE 2,[1B<.ICA0V>+1B<.ICP0V>] jdeactivate channels 6 and 9 
D I C% 

Control always returns to the instruction following the DIC% call. 

When a channel is deactivated, interrupt requests for that channel are 
ignored except for interrupts generated on panic channels (refer to 
Section 4.6) . 



4.10.5 Deassigning Terminal Codes 

| The DT!% monitor call deassigns a terminal code. This call accepts 
J one argument word: the terminal code in AC1. 
I 

| MOVE I 1..TICCE Reassign CTRL/E 

DTI% 

Control always returns to the instruction following the DTI% call. 
This monitor call is ignored if the specified terminal code has not 
been defined by the current job. 



4.10.6 Clearing the Interrupt System 

The CIS% monitor call clears the interrupt system for the current 
process. This call clears interrupts in progress and all waiting 
interrupts. This call requires no arguments, and control always 
returns to the instruction following the CIS call. The RESET% monitor 
call (refer to Section 2.6.1) performs these same actions as part of 
its initializing procedures. 
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4.11 SUMMARY 

To use the software interrupt system, the user's program must: 

1. Supply routines that will process the interrupts. 

2. Set up a channel table containing the addresses of the 
| routines (refer to Section 4.4.2) and a priority level table 

containing the addresses for storing the program counter (PC) 
| values (refer to Section 4. 4. 3) . 

3. Specify the addresses of the tables with the XS I R% monitor 
call (refer to Section 4.4.3). 

4. Enable the software interrupt system with the EIR% monitor 
call (refer to Section 4.5). 

5. Activate the desired channels with the AIC% monitor call 
(refer to Section 4.6) . 
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4.12 SOFTWARE INTERRUPT EXAMPLE 

This program copies one file to another. It accepts the input and 
output filenames from the user. The end of file is detected by a 
software interrupt, and CTRL/E is enabled as an escape character. 

title: software interrupt example 
search monsym 
search macsym 
.require syssmacrel 



J DEFINE STANDARD AC* 



J RELEASE FILES. ETC. 

rGET CURRENT PROCESS SECTION NUMBER 

5 ISOLATE SECTION NUMBER ONLY 

y AND ADD IT TO SERVICE ROUTINE ADDRESSES 

> FOR OUR ROUTINES 

! AND LEVTAB 

J CURRENT PROCESS 

y NUMBER OF WORDS IN ARC BLOCK 

5 PUT NUMBER IN WORD ZERO 

i GLOBAL ADDRESS OF LEVEL TABLE 

5 MOVE IT TO ARGBLK WORD ONE 

i GLOBAL ADDRESS OF CHANNEL TABLE 

5MOVE IT TO ARGBLK WORD TWO 

i GLOBAL ADDRESS OF ARGUMENT BLOCK 

f ENABLE SYSTEM 

ICEGFXI 5 ACTIVATE CHANNELS 



STDAC. 
INTCH1==1 

START : RESET* 

XHLLI Tl » EOF INT 

HLLZS Tl 

IORM TlyCHNTAB+INTCHl 

IORM Tl yCHNTABK ICEOF 

IORM Tl y|..EVTAB + l 

MOVE I Tl y.FHSLF 

MOVE I T2t3 

MOVEM T2v ARGBLK 

XMOVEI T2y LEVTAB 

MOVEM T2tARGBL..K + :I. 

XMOVEI T2rCHNTAB 

MOVEM T2y ARGBLK+2 

XMOVEI T2» ARGBLK 

XSIR% 

EIR% 

MOVE T2H:1B<INTCH1>+1B< 

AICX 

MOVE Tl , I!! , TICCE r y INTCH1 : 

AT 1% 

getif: tmsg <input file: > 

movx tl , gjmld+g jzmsg + gjxcfm+g jxfns+gjxsht 
move t2»c.priinr» .priou.i 

gtjfnx poet filename from user 

erjmp error 1 

MOVEM Tl jINJFN 

getof: tmsg <output file: > 

movx tlygjxfou+gjzmsg+gjzcfm+gjzfns+gjzsht 

MOVE T2yr.PRIINyy.PRI0Un 

GTJFNX J GET FILENAME FROM USER 

ERJMP ERRORS 
MOVEM TIjOUTJFN 

opnif: move tii-injfn 

movx t2 r fld ( 7 , of%bsz ) +ofzrd 
openf% 5 open input file 

erjmp err0r3 

OPNOF: MOVE TlyOUTJFN 

MOVX T2»FLD ( 7 yOF%BSZ ) +OFZUR 



i AS SIGN CTRL/E TO CHANNEL 1 



OPENF% 

erjmp errors 
cpybyt: move ti>inji-n 

BIN% 

MOVE TlyOUTJFN 
BOUT% 

JRST CPYBYT 
DONE: MOVE TlylNJFN 
CLOSF% 

JFCL 
MOVE TlyOUTJFN 
CLC)SF% 

JFCL 
HALTFZ 



?OPEN OUTPUT FILE 



5 READ INPUT BYTE 

» WRITE OUTPUT BYTE 
SLOOP UNTIL EOF 

S CLOSE INPUT FILE 



5 CLOSE OUTPUT FILE 



4-21 



USING THE SOFTWARE INTERRUPT SYSTEM 



J ROUTINE TO HANDLE "'E 



ABORTS OPERATION 



CTRLEt MOVEI T:l. ,.PRIOU 
CFOEFZ 

TMSG < ABORTED. > 
CISX 
JRST START 



J CLEAR OUTPUT DUFFER 
S INFORM USER 
5 CLEAR SYSTEM 



• ROUTINE TO HANDLE EOF ■■•■ COMPLETES OPERATION NORMALLY 



EOF I NT! MOVEM T:l. xINTACl 
X MO WE I T If DONE 
MOVEM T:l. iPC2+l 
MOVE T1»INTAC1 
DEBRKZ 



J SAVE ACs» 

5 CHANGE PC 

»TO DONE 

i RESTORE ACs 

f DISMISS INTERRUPT 



} LEVEL TABLE 
LEVTAB! 

PC2 


PC2J BLOCK 2 
', CHANNEL TABLE 

chntab: o 

FLD < 2 1 S I%LE V ) ! FLD < CTRLE t SI %ADR ) 

REPEAT "D8>«» 

FLD ( 2 1 SIXLEV ) ! FLD < EOF I NT » S I ZADR > 

REPEAT "D25»«» 
ARGBLKS BLOCK 3 
INJFNi BLOCK 1 
OUTJFNJ BLOCK 1 
INTACi: BLOCK I 
ERROR i: TMSG < 
riNVALID FILE SPECIFICATION!:- 

HALTF7. 
ERR0R2J TMSG < 
'INVALID FILE SPECIFICATIONS- 

HALTFZ 
ERRORS? TMSG < 
? CANNOT OPEN FILE> 

HALTFK 

LIT 

END START 
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CHAPTER 5 
PROCESS STRUCTURE 



As stated in Chapter 1, the TOPS-20 operating system allows each job 
to have multiple processes that can run simultaneously. Each process 
has its own environment called its address space. Associated with the 
environment is the program counter (PC) of the process and a 
j well-defined relationship with other processes in the job. In 
| TOPS-20, the term fork is synonymous with the term process. 

The TOPS-20 operating system schedules the running of processes, not 
entire jobs. A process can be scheduled independent of other 
processes because it has a definite existence: its beginning is the 
time at which it is created, and its end is the time at which it is 
killed. At any point in its existence, a process can be described by 
its state, which is represented by a status word and a PC word (refer 
to Section 5.9) . 
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The relationships among processes in a job are shown in the diagram 
below. Each process has one immediate superior process (except for 
the top-level process) and can have one or more inferior processes. 
Two processes are parallel if they have the same immediate superior. 
A process can create an inferior process but not a parallel or 
superior process. 





Top-Level 
Process 
































Process 
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Process 
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Process 
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Process 
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Process 1 is the superior process of process k, and process 3 is the 
superior of process 5. Processes *t and 5 are the inferiors of 
processes 1 and 3» respectively. Process 2 has no inferior process. 
Processes 1, 2 and 3 are parallel because they have the same superior 
process (the top-level process). Processes h and 5» although at the 
same depth in the structure, are not parallel because they do not have 
the same superior process. Process 1 created process k but could not 
have created any other process shown in the structure above. 



5-1 USES FOR MULTIPLE PROCESSES 

A multiple-process job structure allows: 

1. One job to have more than one program runnable at the same 
time. These programs can be independent programs, each one 
compiled, debugged, and loaded separately. Each program can 
then be placed in a separate process. These processes can be 
parallel to each other, but are inferior to the main process 
that created them. This use allows parallel execution of the 
individual programs. 

2. One process to wait for an event to occur (for example, the 
completion of an I/O operation) while another process 
continues its computations. Communication between the two 
processes is such that when the event occurs, the process 
that is computing can be notified via the software interrupt 
system. This use allows two processes within a job to 
overlap I/O with computations. 
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One application of a multiple-process job structure is the following 
situation: a superior process is responsible for accepting input from 
various terminals. After receiving this input, the process sends it 
to various inferior processes as data. These inferior processes can 
then initiate other processes, for example, to write reports on the 
data that was received. 



TTY 



Process that 
Accepts Input 
from Terminals 



TTY 



Processes that 
Receive the 
Input as Data 



Processes that 
Write Reports 
on the Data 



Another application is that used for the user interface on the 
DECSYSTEM-20. On the DECSYSTEM-20, the top-level process in the job 
structure is the Command Language. This process services the user at 
the terminal by accepting input. When the user runs a 
example, MACRO, FORTRAN), the Command Language process 
inferior process, places the requested program in it, and executes it. 
The Command Language can then wait for an event to occur, either from 
the program or from the user. An event from the program can be its 
completion, and an event from the user can be the typing of a certain 
terminal key (CTRL/C, for example). 



program (for 
creates an 



5.2 PROCESS COMMUNICATION 

| A process can communicate with or control other processes in the 
system in several ways: 

• direct process control 

• software interrupts 

• IPCF and ENQ/DEQ facilities 

• memory sharing 
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5.2.1 Direct Process Control 

A process can create and control other processes inferior to it within 
the job structure. The superior process can cause the inferior 
process to begin execution and then to suspend and later resume 
execution. After the inferior process has completed its tasks, the 
superior process can delete the inferior from the job structure. 

Some of the monitor calls used for direct process control are: 
CF0RK%, to create a process; SF0RK%, to start a process; WF0RK%, to 
wait for a process to terminate; RFSTS%, to obtain the status of a 
process; and KF0RK%, to delete a process. Refer to the TOPS-20 
Moni tor Cal Is Reference Manual for descriptions of additional monitor 
calls dealing with process control. 



5.2.2 Software Interrupts 

The software interrupt facility enables a process to receive 
asynchronous signals from other processes, the system, or the terminal 
user or to receive signals as a result of its own execution. For 
example, a superior process can enable the interrupt system so that it 
receives an interrupt when one of its inferiors terminates. In 
addition, processes within a job structure can explicitly generate 
interrupts to each other for communication purposes. 

Some of the monitor calls used when communication occurs via the 
software interrupt system are: SIR%, to specify the interrupt tables; 
EIR%, to enable the interrupt system; AIC%, to activate the interrupt 
channels; and IIC%, to initiate an interrupt on a channel. Refer to 
Chapter h and Section 5-10 for more information. 



5.2.3 IPCF and ENQ/DEQ Facilities 

The Inter-Process Communication Facility (IPCF) enables processes and 
jobs to communicate by sending and receiving informational messages. 
The MSEND% call is used to send a message, the MRECV% call is used to 
receive a message, and the MUTIL% call is used to perform utility 
functions. Refer to Chapter 7 for descriptions of these calls. 

The ENQ/DEQ facility allows cooperating processes to share resources 
and facilitates dynamic resource allocation. The ENQ% call is used to 
obtain a resource, the DEQ% call is used to release a resource, and 
the ENQC% call is used to obtain status about a resource. Refer to 
Chapter 6 for descriptions of these calls. 
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5. 2. ^ Memory Sharing 

Each page or section in a process' address space is either private to 
the process or shared with other processes. Pages are shared among 
processes when the same page is represented in more than one process' 
address space. This means that two or more processes can identify and 
use the same page of physical storage. Even when several processes 
have identified the same page, each process can have a different 
access to that page, such as access to read or write that page. 

A type of page access that facilitates sharing is the copy-on-wr i te 
access. A page with this access remains shared as long as all 
processes read the page. As soon as a process writes to the page, the 
system makes a private copy of the page for the process doing the 
writing. Other processes continue to read and execute the original 
page, This access provides the capability of sharing as much as 
possible but still allows the process to change its data without 
changing the data of other processes. A monitor call used when 
sharing memory is PMAP%. Refer to Section 5-6.2 for more information. 



5.3 PROCESS IDENTIFIERS 

In order for processes to communicate with each other, a process must 
have an identifier, or handle, for referencing another process. When 
a process creates an inferior process, it is given a handle on that 
inferior. This handle is a number in the range 400001 to 400777 and 
is meaningful only to the process to which it is given (that is, to 
the superior process). For example, if process A creates process B, 
process A is given a handle (for example, 400003) on process B. 
Process A then specifies this handle when it uses monitor calls that 
refer to process B. However, process B is not known by this handle to 
any other process in the structure, including itself. The handle 
400003 may in fact be known to process B, but it would describe a 
process inferior to process B. For this reason, process handles are 
sometimes called "relative fork handles" because they are relative to 
the process that created them. 

There are several standard process handles that are never assigned by 
the system but have a specific meaning when used by any process in the 
structure. These handles are used when a process needs to communicate 
with a process other than its immediate inferior or with multiple 
processes at once. These handles are described in Table 5~1« 
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Table 5-1: Process Handles 



Number 



200000 



-3 
-k 



Symbol 



400000 .FHSLF 
400000+n 



FH%EPN 



FHSUP 



FHTOP 



.FHSAI 



.FHINF 



.FHJOB 



Meani ng 



The current process (or self) . 

Process n, relative to the current 
process. 

Extended page number (see PM%EPN in 
PMAP%) . When used in conjunction with 
the above two forms, this bit 
indicates that addresses and/or page 
numbers are interpreted as absolute, 
not relative to the PC section of the 
program executing the JSYS. This bit 
has no meaning for programs that do 
not use extended addressing. 

The immediate superior of the current 
process. 

The top-level process in the job 
structure. 

The current process and all of its 
i nfer iors. 

All of the inferiors of the current 
process. 

All processes in the job structure. 
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Consider the job structure below. 
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The following indicates the specific process 
referenced if process E gives the handle: 



or processes being 



.FHSLF refers to process E 

.FHSUP refers to process D 

.FHTOP refers to process A 

.FHSAI refers to processes E, G, and H 

.FHINF refers to processes G and H 

.FHJOB refers to processes A through H 

The process must have the appropriate capability enabled in its 
capability word to use the handles .FHSUP, .FHTOP, and .FHJOB (refer 
to Section 5-5-1) . 

Process E can reference one of its inferiors (for example, G) with the 
handle it was given when it created the inferior. Process E can 
reference other processes in the structure (for example, F) by 
executing the GFRKS% monitor call to obtain a handle on the desired 
process. Refer to the TOPS-20 Monitor Cal Is Reference Manual for a 
description of the GFRKS% call. 
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5. It OVERVIEW OF MONITOR CALLS FOR PROCESSES 

Monitor calls exist for creating, loading, starting, suspending, 
resuming, interrupting, and deleting processes. When a process is 
created, its address space is assigned, and the process is added to 
the job structure of the creating process. The contents of its 
address space can be specified at the time the process is created or 
at a later time. The process can also be started at the time it is 
created. A process remains potentially runnable until it is 
explicitly deleted or its superior is deleted. 

A process may be suspended if one of the following conditions occurs: 

1. The process executes an instruction that causes a software 
interrupt to occur, and it is not prepared to process the 
i nterrupt. 

2. The process executes the HALTF% monitor call. 

3. The superior process requests suspension of its inferior. 

k. The superior process is suspended. When a process is 
suspended, all of its inferior processes are also suspended. 

5. A monitor call is trapped. (Refer to TF0RK% monitor call in 
the TOPS-20 Moni tor Cal Is Reference Manual) . 



5-5 CREATING A PROCESS 

A process creates an inferior process by executing the CF0RK% (Create 
I Process) monitor call. This monitor call allows the caller to specify 
j the address space, capabilities, initial contents of the ACs, and PC 

for the inferior process and to start the execution of the inferior. 

The CF0RK% call accepts two words of arguments in AC1 and AC2. 

AC1: characteristics for the inferior in the left half, and PC 
address for the inferior in the right half. 

AC2: address of a 20 (octal) word block containing the AC 
values for the inferior. 

I The characteristics for the inferior process are described in Table 
I 5-2. 
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| Table 5 - 2: Inferior Process Characteristic Bits 



Bit 



Symbol 



Meani ng 



CR%MAP 



Set the map of the inferior process to the 
same as the map of the superior (creating) 
process. This means that the superior and 
the inferior will share the same address 
space. Changes made by one process will be 
seen by the other process. 



If thi s bit is not 



on 



i n 



the cal 1 , the 



inferior's map will contain all zeros. If 

desired, the creating process can then use 

PMAP or GET to add pages to the inferior's 
map. 

CR%CAP Set the capability word of the inferior 
process to the same as the capability word of 
the superior process. (Refer to Section 
5 ♦ 5 • 1 for the description of the capability 
word.) 



CR^ACS 



CR%ST 



If this bit is not on in the call, the 
inferior will have no special capabilities. 

Reserved for Digital (must be 0). 

Set the ACs of the inferior process to the 
values beginning at the address given in AC2. 

If this bit is not on in the call, the 
inferior's ACs will be set to zero, and the 
contents of AC2 is ignored. 

Set the PC for the inferior process to the 
address given in the right half of AC1 and 
start execution of the inferior. 



18-35 



CR%PCV 



If this bit is not on in the call, the right 
half of AC1 is ignored, and the inferior is 
not started. If desired, the creating 
process can then use SF0RK% or XSFRK% to 
start the newly created process. 

PC value for inferior process if CR%ST is on. 
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If execution of the CF0RK% call is not successful, the inferior 
process is not created and an error code is returned, as described in 
Section 1.2.2. 

If execution of the CF0RK% call is successful, the inferior process is 
created and its process handle is returned in the right half of AC1. 
This handle is then used by the superior process when communicating 
with its inferior process. The execution of the program in the 
superior process continues at the second instruction following the 
CF0RK% call. The inferior begins execution at the location contained 
in bits 18-35 (CR%PCV) if CR%ST is specified. 

Assume that process A executes the CF0RK% monitor call twice to create 
two parallel inferior processes. This is represented pictorial ly 
be 1 ow . 



Process A 
Creates Process B 
by Executing a CFORK 



Process B Is Created 
and Its Handle Is 
Given to Process A 





Process A Executes 
Another CFORK to 
Create Process C 


























Process B 




Process C Is Created 
and Its Handle 
Given to Process A 



Note that process A has been given two handles, one for process B and 
one for process C. Process A can refer to either of its inferiors by 
giving the appropriate handle or to both of its inferiors by giving a 
handle of -k (.FHINF) . 
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5 • 5 • 1 Process Capabilities 

When a new process is created, it is given the same capabilities as 
its superior, or it is given no special capabilities. This is 
indicated by the setting of the CR%CAP bit in the CF0RK% call. The 
capabilities for a process are indicated by two capability words. The 
first word indicates if the capability is available to the process, 
and the second word indicates if the capability is enabled for the 
process. This second word is the one being set by the CR%CAP bit in 
the CF0RK% cal 1 . 

Types of capabilities represented in the capability words are job, 
process, and user capabilities. Each capability corresponds to a 
particular bit in the capability words and thus can be activated and 
protected independently of the other capabilities. Refer to the 
TOPS-20 Moni tor Cal Is Reference Manual for more information on the 
capabi 1 i ty words. 



5.6 SPECIFYING THE CONTENTS OF THE ADDRESS SPACE OF A PROCESS 

Once a process is created, the contents of its address space can be 
specified. This can be accomplished in one of three ways. As 
mentioned in Section 5.5, bit CR%MAP can be set in the CF0RK% call to 
indicate that the address space of the inferior process is to be the 
same as the address space of the creating process. In addition, the 
creating process can execute the GET% monitor call to map specified 
pages from a file into the address space of the inferior process. 
Finally, the creating process can execute the PMAP% monitor call to 
map specified pages from another process into the address space of the 
inferior process. 

If the creating process does not specify the contents of the 
inferior's address space, the address space will be filled with zeros. 



5.6.1 GET% Monitor Cal 1 

The GET% monitor call gets a save file, copying or mapping it into the 
process as appropriate. It updates the monitor's data base for the 
process by copying the entry vector and the list of program data 
vector addresses (PDVAs) from the save file. (See the .POADD function 
of the PDV0P% monitor call.) 

This call can be executed for either sharable or nonsharable save 
files that were created with the SSAVE% or SAVE% monitor call, 
respectively. The file must not be open by any process in the user's 
job. (Refer to the TOPS-20 Monitor Cal Is Reference Manual for more 
information regarding the PDV0P%, SSAVE%, and SAVE% monitor calls.) 
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The GET% monitor call accepts two words of arguments in AC1 and AC2. 
The first word specifies the handle of the desired process, flag bits, 
and the JFN of the desired file. The second word specifies where the 
pages from the file are to be placed in the address space of the 
process. Thus, 

AC1: process handle,, flag bits and a JFN 

AC2: lowest process page number in left half, and highest 
process page number in right half; or the address of an 
argument block. If this AC contains page numbers, those 
page numbers control the parts of memory that are loaded 
when GT%ADR is on in AC1. 

Table 5 - 3 describes the bits that can be set in AC1 . 



Table 5"3: GET% Flag Bits 



Bit 



Symbol 



Meani ng 



19 



20 



GT%ADR Use the memory address limits given in AC2. 
If this bit is off, all existing pages of 
the file (according to its directory) are 
mapped. 

GT%PRL Preload the pages being mapped (move the 

pages immediately.) If this bit is off, the 

pages are read in from the disk when they 
are referenced. 



21 



22 



24-25 



GT%N0V Do not overlay existing pages and do return 
an error. If this bit is off, existing 
pages will be overlaid. 

GT%ARG If this bit is on, AC2 contains the address 
of an argument block. 

GT%JFN JFN of the save f i 1e. 
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The format of the argument block is described in Table 5~k. 
Table 5-4: GET% Argument Block 

Word Symbol Meaning 



.GFLAG Flags that indicate how the rest of the 
argument block is to be used. 

.GLOW Number of the lowest page in the process 
into which a file page gets loaded. This 
page must be within the section specified 
by .GBASE. 

.GHIGH Number of the highest page in the process 
into which a file page gets loaded. This 
page must be within the section specified 
by .GBASE. 

■GBASE Number of the section into which the file 
pages are loaded. You can specify the 
section for single-section save files only; 
use of this word with a multiple-section 
save file causes an error. The file pages 
are loaded into this section of memory 
regardless of the section specified in the 
save file. 



5-13 



PROCESS STRUCTURE 



Table 5-5 describes the flag bits defined for use in .GFLAG, 



Table 5~5: GET% Argument Block Flags 



Bit 



Symbol 



Meani ng 



GT%L0W .GLOW contains the number of the lowest 
page within the process to use. 

GT%HGH .GHIGH contains the number of the highest 
page within the process to use. 

GT%BAS .GBASE contains the number of the section 
to use. 
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When the pages of the file are mapped into pages in the process's 
address space, the previous contents of the process pages are 
overwritten. Any full pages in the process that are not overwritten 
are unchanged. Any portions of process pages for which there is no 
data in the file are filled with zeros. 

For example, a GET% call executed for a file that contains 2 1/2 pages 
sets up the process' address space as shown in the following diagram. 



Page 1 



Page 2 



Page 3 



Process 



File 



Data 



Data 



Data 



GET 

Call 



Page 4— 

Page 512 Unchanged 



Data 



Data 



Data 



EOF 



Page 1 



Page 2 



Page 3 



| After execution of the GET% call, control returns to the user's 
program at the instruction following the call. If an error occurs, a 
software interrupt is generated, which the program can process via the 
software interrupt system. 
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5.6.2 PMAP% Monitor Cal 1 

The PMAP% monitor call is used to map pages from one process to the 
address space of a second process. Data is not actually transferred; 

I only the contents of the page map of the second (that is, destination) 

j process are changed. 

The PMAP% monitor call accepts three words of arguments in AC1 through 

AC3. The first word contains the handle and page number of the first 

I page to be mapped in the source process (that is, the process whose 

j pages are being mapped). The second word contains the handle and page 

j number of the first page to be mapped in the destination process (that 

j is, the process into which the pages are being mapped). The third 

word contains a count of the number of pages to map and bits 

indicating the access that the destination process will have to the 

pages mapped. Thus, 

AC1: source process handle in the left half, and page number in 
the process in the right half. 

AC2: destination process handle in the left half, and page 
number in the process in the right half. 

AC3: count of number of pages to map and the access bits. 

The count and access bits that can be specified in AC3 are described 
I i n Section 3-5-6. 1 . 

Upon successful execution of the PMAP% call, addresses in the 
destination process actually refer to addresses in the source process. 
The contents of the destination page previous to the execution of the 
call have been deleted. The access requested in the PMAP% call is 
granted if it does not conflict with the current access of the 
destination page (that is, an AND operation is performed between the 
specified access and the current access). Control returns to the 
user's program at the instruction following the PMAP% call. If an 
error occurs, an illegal instruction trap is generated, which the 
program can process via the software interrupt system or with an ERJMP 
or ERCAL instruction. 



5-7 STARTING AN INFERIOR PROCESS 

A program in an inferior process can be started in one of two ways. 
As mentioned in Section 5-5t the superior process can specify in the 
CF0RK% call the PC for the inferior process and start its execution. 
Alternatively, the superior process, after executing the CF0RK% call 
to create an inferior process, can execute the SF0RK% (Start Process) 
monitor call to start it. 
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The SFORK% monitor call accepts two words of arguments in AC1 and AC2. 

AC1: flags, .process handle 

F 1 ags: 

SF%CON(1BO) Used to continue a process that has 
previously halted. If SF%C0N is set, the 
address in AC2 is ignored, and the process 
continues from where it was halted. 

AC2: the PC of the process being started. The PC contains flags 
in the left half and the process starting address in the 
right half. This call obtains the section number of the 
PC from the entry vector of the process. 

There are two alternative ways to start processes: XSFRK% (see 
Section 8.3.2) or SFRKV% (see the TOPS-20 Monitor Cal Is Reference 
Manual ) . 

The process handle given in AC1 cannot refer to a superior process, to 
more than one process (for example, .FHINF), or to a process that has 
already been started. 

After execution of the SF0RK% call, control returns to the user's 

program at the instruction following the call. If an error occurs, a 

software interrupt is generated, which the program can process via the 
software interrupt system. 



5.8 INFERIOR PROCESS TERMINATION 

The superior process has one of two ways in which it can be notified 
when one or more of its inferiors terminate execution: via the 
software interrupt system or by executing the WF0RK% monitor call. An 
inferior process will terminate normally when it executes a HALTF% 
monitor call. Alternatively, the process will terminate abnormally 
when it executes an instruction that generates a software interrupt, 
such as an illegal instruction, and it has not activated the 
appropriate channel. 

By activating channel .ICIFT (channel 19) for inferior process 
termination and enabling the software interrupt system, the superior 
process will receive an interrupt when one of its inferiors 
terminates. (Refer to Section h.6 for information on activating 
channel .ICIFT.) The interrupt occurs when any inferior process 
terminates. Use of the interrupt system allows the superior to do 
other processing until an interrupt occurs, indicating that an 
inferior process has terminated. 
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In some cases, however, the superior cannot do additional processing 
until either a specific process or all of its inferior processes have 
completed execution. If this is the case, the superior process can 
execute the WF0RK% (Wait Process) monitor call. This call blocks the 
superior until one or all of its inferiors have terminated. 

The WF0RK% monitor call accepts one argument in AC1, the handle of the 
desired process. This handle can be .FHINF (-*») to block the superior 
until all inferiors terminate, but cannot be a handle on a superior 
process. 

After execution of the WF0RK% monitor call, control returns to the 
user's program at the instruction following the call, when the 
specified process or all of the inferior processes terminate. If an 
error occurs, it generates a software interrupt, which the program can 
process via the software interrupt system. 



5-9 INFERIOR PROCESS STATUS 

The superior process can obtain the status of one of its inferiors by 
executing the RFSTS% (Read Process Status) monitor call. This call 
returns the status and PC words of the given inferior process. 

The short form of the RFSTS% monitor call accepts one argument in AC1, 
the handle of the desired process. This handle cannot refer to a 
superior process or to more than one process. The long form accepts 
two argument words: flags,, process handle in AC1 and the address of 
the status return block in AC2. In the long form, RF%LNG (bit 0) is 
set in AC1 and bits 1-17 are unused (must be zero). 

After execution of the short form of the RFSTS% call, control returns 
to the user's program at the instruction following the call. If the 
RFSTS% call is successful, AC1 contains the status word of the given 
process and AC2 contains the PC word. The status word is shown in 
Table 5~6\ 
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Table 5-6: Process Status Word 

Bit Symbol Meaning 



RF%FRZ The process is suspended (that is, frozen). 
If this bit is not on, the process is not 
suspended. 



1-17 RF%STS The status of the process. 

Value Symbol Meaning 



.RFRUN The process is 
runnable. 

.RFIO The process is halted 
waiting for I/O 

.RFHLT The process is halted 
by a HF0RK% or HALTF% 
monitor call or was 
never started. 

.RFFPT The process is halted 
by the occurrence of a 
software interrupt for 
which it was not 
prepared to handle. 
The right half of the 
status word contains 
the number of the 
channel on which the 
interrupt occurred. 

•RFWAT The process is halted 
waiting for another 
process to terminate. 

.RFSLP The process is halted 
for a specified amount 
of time. 
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Table 5-6: Process Status Word (Cont.) 



Bit 



Symbol 



Meani ng 
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Value Symbol Meaning 

6 .RFTRP The process is 

dismissed because it 
was intercepted by its 
super ior . 

7 .RFABK The process is 

dismissed because 
address break was 
encountered. 

The channel number on which an interrupt 
occurred, which the process was not 
prepared to handle (see process status code 
.RFFPT above) . 



The RFSTS% call returns with -1 (fullword) in AC3 if the specified 

handle is assigned but refers to a deleted process. The call 

generates an illegal instruction interrupt if the handle is 
unassi gned. 

| In the long form of the RFSTS% monitor call, RF%LNG is set in AC1 and 

j AC2 contains the address of a status-return block. On the return, AC1 

j and AC2 are not modified. The status-return block is described in 

j Table 5"7- 
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| Table 5"7 : RFSTS% Status-Return Block 



Word Symbol Meaning 



.RFCNT Count of words returned in this block in the 

left half, and count of maximum number of 
words to return in right half (including this 
word). The right half of this word is 
specified by the user. 

1 .RFPSW Process status word. This word has the same 

format as AC1 on a return from a short call. 
If a valid, but unassigned, process handle 
was specified in AC1, then this word contains 
-1 and no other words are returned. 

2 .RFPFL Process PC flags. These are the same flags 

returned in AC2 on a short call. 

3 .RFPPC Process PC. This is the address; no flags 

are returned in this word. 



k .RFSFL Status flag word. 

F lags: 



Bit Symbol Meaning 

BO RF%EX0 Process is execute-only, 



If an error occurs during execution of the RFSTS% call, a software 
interrupt is generated which the program can process via the software 
interrupt system. 
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5-10 PROCESS COMMUNICATION 

A superior process can communicate with its inferiors by sharing the 
same pages of memory. This sharing is accomplished with the CF0RK% 
(bit CR%MAP) or the PMAP% monitor call. When the superior executes 
either of these calls, both the superior and the inferior share the 
same pages. Changes made to the shared pages by either process will 
be seen by the other process. 

Alternatively, processes can communicate via the software interrupt 
system. The superior process can cause a software interrupt to be 
generated in an inferior process by executing the I I C% (Initiate 
Interrupt on Channel) monitor call. For this type of communication to 
occur, the inferior's interrupt channels must be activated and its 
interrupt system enabled. 

The IIC% monitor call accepts two words of arguments in AC1 and AC2. 
The handle of the process to receive the interrupt is given in the 
right half of AC1. AC2 contains a 36-bit word, with each bit 
representing one of the 36 software channels. If a bit is on in AC2, 
a software interrupt is initiated on the corresponding channel. For 
example, if bit 5 is on in AC2, an interrupt is initiated on channel 
5. Thus, 

AC1: process handle in the right half 

AC2: 36-bit word, with bit n on to initiate a software interrupt 
on channel n 

The process handle given cannot refer to a superior process or to more 
than one process. 

After execution of the I I C% call, control returns to the user's 
program at the instruction following the call. If an error occurs, it 
generates a software interrupt which the program can process via the 
software interrupt system. 
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5-11 DELETING AN INFERIOR PROCESS 

A process is deleted from the job structure when the superior process 
executes the KF0RK% (Kill Process) monitor call. When a process is 
deleted, its address space, its handle, and any JFNs acquired by the 
process are released. If the process being deleted has processes 
inferior to it, the inferiors are also deleted. For example, in the 
structure: 



Process A 






Process B 






Process C 
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if process A deletes process B by executing a KF0RK% call, process C 
is also deleted. 

The KF0RK% monitor call accepts one argument in the right half of AC1, 
the handle of the process to be deleted. This handle cannot refer to 
a superior process, to more than one process (for example, .FHINF), or 
to the process executing the call (that is, .FHSLF). The RESET% 
monitor call is used to reinitialize the current process; refer to 
Section 2.6.1. 

After execution of the KF0RK% call, control returns to the user's 
program at the instruction following the call. If an error occurs, a 
software interrupt is generated, which the program can process via the 
software interrupt system. 
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5.12 PROCESS EXAMPLES 

Example 1 - This program creates an inferior process to provide timing 
interrupts. 

title tim i nt -- an inferior process providing timing interrupts 

search monsym 
search macsym 
.require sysjmacrel 

sid ac. 5 define standard acs 

start! re set % 5 re lease files, etc. 
move p»i::h)wd pdlsiz>.pdl::i ( initialize stack 

movx t1. ycr/jmap (make new process share this process's memory 

c fork x (create a new process 

e j s h l t sun e x p e c t e b f a t a i... e r r r 

movem t:l. :- handle ( save process handle 

(here tci start the inferior process 

stprocs setzb 14 > flag ( initialize counter and flag 

MOVE i":l. v HANDLE {GET PROCESS HANDLE 

MOVE I T 2> SLEEP ; GET ADDRESS TO START PROCESS 

SFORK% 3 START THE NEW PROCESS 

E J S H L T ( U N E X P E C T E D I" A T A I... E R R R 

( MAIN PROCESSING LOOP 

LOOP! AOS T4 (INCREMENT COUNTER 

SKIPN FLAG (HAS TIME ELAPSED YET? 

JRST LOOP 5 NO » GO DO MORE PROCESSING 

? HERE WHEN LOWER PROCESS HAS INTERRUPTED 

TMSG < 

Counter has reached > (OUTPUT FIRST PART OF MESSAGE 

MOVX T :l. , . P R 1 U 56 E T P R I M A R Y U T P U T D E S I G N A T R 

MOVE T2,T4 (GET VALUE OF COUNTER 

MOVE I T3»"D:l.<> (USE DECIMAL RADIX 

NOU'rZ (OUTPUT CURRENT COUNTER VALUE 

EJSERR (PRINT ERROR MESSAGE AND CONTINUE 
TMSG < 

(MOVE TO A NEW LINE 

JRST STPROC (CONTINUE COUNTING 

( PROGRAM PERFORMED BY INFERIOR PROCESS TO WAIT FOR ONE-HALF MINUTE 

SLEEP! MOVX Tl »'" 1)30* "13 1000 (ONE- HALF MINUTE IN MILLISECONDS 

DISMS% (WAIT FOR SPECIFIED TIME 

SE TOM FLAG (TELL SUPERIOR TIME HAS ELAPSED 

HALTF% (FINISHED 

5 CONSTANTS AND STORAGE 

PDLSIZ — 50 (SIZE OF THE STACK 

PDL! BLOCK PDLSIZ (STACK 

HANDLE; BLOCK :l. (INFERIOR PROCESS HANDLE 

FLAG! BLOCK 1 (INTERRUPT FLAG 

END START 
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Example 2 - This program illustrates how an inferior process may be 
used as a source of timer interrupts. The main program increments a 
counter. It has an inferior process running for the sole purpose of 
timing 10 second intervals. Each time the inferior process has timed 
10 seconds, it stops and interrupts the main program. The main 
program then reports how many more times it has incremented the 
counter since the last 10 second interrupt. 

TITLE TRMINT ■- FORK TERMINATION INTERRUPTS 
SEARCH MONSYM 
SEARCH MACSYM 
.REQUIRE SYS 5 M ACRE I... 

STDAC. i DEFINE STANDARD ACS 

START? RESET* S RELEASE FILES , ETC. 

MOVE P f 1 1 W D P D LSIZy P DLJ PIN I T I A L I Z E STAC K 

i SET UP THE INTERRUPT SYSTEM 

MOVX T.I. f.FHSLF J GET PROCESS HANDLE FOR THIS FORK 

MOVE T2fCLEVTABf fCHNTAB::I SGET TABLE ADDRESSES 

sirx 5 set interrupt table addresses 

ejshlt .unexpected fatal error 

movx t2f.i.b<.:i:c:i:ft> soft process termination channel bit 

aic/c 5 activate process termination channel 

ejshlt 5 li n e x p e c t e d fatal.. err r 

eir/i 5 enable interrupt system 

ejshlt 5 unexpected fatal error 

f CREATE AND START THE INFERIOR PROCESS 

M V X T 1 t C R X M A P ■)■ C R X S T + S I... E E P 

CFORK% } CREATE AND START TIMER AT SLEEP 

EJSHLT 5 UNEXPECTED FATAL ERROR 

MOVEM TIf HANDLE SSAVE PROCESS HANDLE 

INITIALIZE THE COUNTER 

STPROC! SETZB T4fOLDT4 5 CLEAR COUNTER 

»MAIN LOOP OF THE PROGRAM WHICH JUST KEEPS COUNTING. (REAL 
(APPLICATION WOULD PRESUMABLY HAVE A MORE USEFUL MAIN PROGRAM.) 

LOOP! AOJA T4fL00P SJUST KEEP INCREMENTING 

i HERE WHEN LOWER PROCESS HAS INTERRUPTED 

PROINTJ MOVEM PfIACS+P 5 SAVE STACK POINTER 

MOVE I PfIACS 5 MAKE POINTER FOR REST OF ACS 

BLT PfIACS+CX SSAVE REST OF ACS 

MOVE PfIACS+P y RESTORE P 

TMSG < NUMBER OF COUNTS? > 

M V X TIf. P R 1 U 5 G E T PRIMARY OUTPUT DESIGNATOR 

EXCH T4fOI...DT4 5 SAVE NEW COUNTER VALUE 

SUB T4fOI...DT4 5 FIND NUMBER OF COUNTS SINCE LAST TIME 

MOVM T2fT4 5 MAKE IT POSITIVE 

MOVE I T3f"D10 jIJSE DECIMAL RADIX 

N U T % i U T P U T C U R R E N T C U N T E R V A I... U E 

EJSERR SPRINT ERROR MESSAGE AND CONTINUE 

TMSG < 

> SMOVE TO A NEW LINE 

MOVE T :l f H A N D L E 5 G E T p R C E S S HANDLE 

MOVE I T2f BLEEP 5 GET ADDRESS TO START PROCESS 

S FORK IX 5 START THE NEW PROCESS 

E J S H I... T 5 U N E X P E C T E D FATA I... E R R R 

MOVSI PfIACS SGET POINTER TO SAVED ACS 

BLT PfP S RESTORE SAVED ACS 

D E B R K "A f D I S M I S S INTERRUPT 
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ST HE FOLLOWING IS EXECUTED AS A LOWER PROCESS TO DO THE 
STIMING. IT SLEEPS FOR 10 SECONDS AND THEN STOPS. 

SLEEP! MOVX T:l. , '"D:I.O#"D 1.000 S:I.O SECONDS IN MILLISECONDS 
niSMSZ 5SLEEP 

HALTF/i iSTOP AND I NT ERR LIFT THE MAIN PROGRAM 

f CONSTANTS AND STORAGE 

pSIZE 01- THE STACK 
J STACK 

:!EXP <)> ? CHANNELS 0-1 8 ARE NOT USED 

5 LEVEL 1 PROCESS TERMINATION CHANNEL 

::EXP 0> r REMAIN I NO CHANNELS ARE NOT USED 

i RETURN PC STORED AT RETPCl FOR LEVEL 

! LEVEL 2 NOT USED 

5 LEVEL 3 NOT USED 

J INFERIOR PROCESS HANDLE 

5 RETURN PC STORED HERE ON INTERRUPTS 

i HOLDS TIMER VALUE AT LAST INTERRUPT 

i STORAGE FOR ACS DURING INTERRUPTS 





PDI..SIZ='=50 


PDL X 


BLOCK PDLSIZ 


chntab: 


REPEAT "H19t 




X, » PRO I NT 




REPEAT "DISr 


levtabj 


RETPCl 












handle: 


BLOCK 1 


RETPCl? 


BLOCK 1 


0L.DT4: 


BLOCK J. 


I ACS! 


BLOCK 20 




END START 
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Example 3 - This program creates an inferior process which waits until 
a line has been typed on the terminal. 

title: frkdoc •••■ an inferior process waits until a line is typed 

search monsym 
search macsym 
.require sybimacrel 

stdac. v define standard acs 

start: RESETX .RELEASE FILES.. ETC. 

move p.eiowd pdls:i:z„pdl:i ? initialize stack 

movx tl .crxmap vmake new process share this process's memory 

cforkx ', create a new process 

ejshlt i unexpected fatal error 

setzb t4.flag $ initialize counter and flag 

movei t2.getc0m i get address to start process 

bforkz j start the new process 

ejshlt ) unexpected fatal error 

5 main processing loop 

loop? aos t4 5 increment counter 

skipn flag } has time elapsed yet? 

jrst loop j no? go do more processing 

i here when inferior process has input a line of text 

TMSG < 

Counter has reached > f OUTPUT FIRST PART OF MESSAGE 

MOVX T1..PRIOU 5GET PRIMARY OUTPUT DESIGNATOR 

MOVE T2.T4 5 GET VALUE OF COUNTER 

MOVEI T3."D10 M.ISE DECIMAL RADIX 

NOUTX .OUTPUT CURRENT COUNTER VALUE 

,. E - : ;SERR } PRINT ERROR MESSAGE AND CONTINUE 

1 MSG <. 

Echo Check! > f OUTPUT FIRST PART OF MFSSAGF 

HRROI Tl. BUFFER .GET POINTER TO BUFFER 

PSOUTX } OUTPUT TEXT JUST ENTERED 

HALTF% J STOP 

JRST START }j.N CASE PROGRAM CONTINUED 

i PROGRAM PERFORMED BY INFERIOR PROCESS TO INPUT A LINE OF TEXT 

GETCOMJ HRROI Tl. BUFFER JGET POINTER TO TEXT BUFFER 

MOVEI T2»BUFSIZ*S J GET COUNT OF MAX # OF CHARACTERS 

SETZM T3 5 NO RETYPE BUFFER 

RDTTYX J READ A LINE FROM THE TERMINAL 

EJSERR i UNEXPECTED ERROR 

SETOM FLAG ?TELL SUPERIOR TIME HAS ELAPSED 

HALTFX 5 FINISHED 

» CONSTANTS AND STORAGE 

PELS 13!- = SO 5 SIZE OF THE STACK 

PDI...: BLOCK PDLSIZ 5 STACK 

BUFSIZ^SO 5 BUFFER SIZE 
BUFFER! BLOCK BUFSIZ 

FLAG! B L C K 1 SIN T E R R t J P T FLAG 

END START 
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ENQUEUE/DEQUEUE FACILITY 



6.1 OVERVIEW 

Many times users are placed in situations where they must share files 
with other users. Each user wants to be guaranteed that while reading 
a file, other users are reading the same data and whiie writing a 
file, no users are also writing, or even reading, the same portion of 
the f i le. 

Consider a data file used by members of an insurance company. When 
many agents are reading individual accounts from the data file, they 
can all access the file simultaneously because no one is changing any 
portion of the data. However, when an agent desires to modify or 
replace an individual account, that portion of the file should be 
accessed exclusively by that agent. None of the other agents wants to 
access accounts that are being changed until after the changes are 
made. 

By using the ENQ/DEQ facility, cooperating users can insure that 
resources are shared correctly and that one user's modifications do 
not interfere with another user's. Examples of resources that can be 
controlled by this facility are devices, files, operations on files 
(for example, READ, WRITE), records, and memory pages. This facility 
can be used for dynamic resource allocation, computer networks, and 
internal monitor queueing. However, control of simultaneous updating 
of files by multiple users is its most common application. 

The ENQ/DEQ facility insures data integrity among processes only when 
the processes cooperate in their use of both the facility and the 
physical resource. Use of the facility does not prevent 
non-cooperating processes from accessing a resource without first 
enqueueing it. Nor does the facility provide protection from 
processes using it in an incorrect manner. 
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A resource is defined by the processes using it and not by the system. 
Because there is competition among processes for use of a resource, 
each resource is associated with a queue. This queue is the ordering 
of the requests for the resource. When a request for the resource is 
granted, a lock occurs between the process that made the request and 
the resource. For the duration of the lock, that process is the owner 
of the resource. Other processes requesting access to the resource 
are placed in the queue until the owner relinquishes the lock. 
However, there can be more than one owner of a resource at a time; 
this is called shared ownership (refer to Section 6.2). Processes 
obtain access to a specific resource by placing a request in the queue 
for the resource. This request is generated by the ENQ% monitor call. 
When finished with the resource, the process then issues the DEQ% 
monitor call. This call releases the lock by removing the request 
from the queue and makes the resource available to the next waiting 
process. This cycle continues until all requests in the queue have 
been satisfied. 



6.2 RESOURCE OWNERSHIP 

Ownership for a resource can be requested as either exclusive or 
shared. Exclusive ownership occurs when a process requests sole use 
of the resource. When a process is granted exclusive ownership, no 
other process will be allowed to use the resource until the owner 
relinquishes it. This type of ownership should be requested if the 
process plans on modifying the resource (for example, the process is 
updating a record in a data file). Shared ownership occurs when a 
process requests a resource, specifying that it will share the use of 
the resource with other processes. When a process is given shared 
ownership, other processes also specifying shared ownership are 
allowed to simultaneously use the resource. Access to a resource 
should be shared as long as any one process is not modifying the 
resource. 

Two conditions determine when a lock to a resource is given to a 
process: 

1. The position of the process's request in the queue for the 
resource. 

2. The type of ownership specified by the process's request. 

Because each resource has only one queue associated with it, requests 
for both exclusive and shared ownership of the resource are placed in 
the same queue. Requests are placed in the queue in the order in 
which the ENQ facility receives them, and the first request in the 
queue will be the first one serviced (except in the case of single 
requests for multiple resources; refer to Section 6.4.1). In other 
words, the ENQ facility processes requests on a first in, first out 
basis. If this first request is for shared ownership, that request 
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will be serviced along with all following shared ownership requests up 
to but not including the first exclusive ownership request. If the 
first request is for exclusive ownership, no other processes are 
allowed use of the resource until the first process has released the 
lock. 

Consider the following queue for a particular resource. 



request 1 (shared) 
request 2 (shared) 



request 3 (exclusive) 
request k (shared) 
request 5 (shared) 



I 



Request 1 will be serviced first because it is the first request in 
the queue. However, since this request is for shared ownership, 
request 2 can also be serviced. Request 3 cannot be serviced until 
the processes with request 1 and request 2 release the lock on the 
resource. Eventually the lock is released by the two processes, and 
the first two requests are removed from the queue. The queue now has 
the following entries: 






request 3 (exclusive) 

request 4 (shared) 
I _ 

! request k (shared) 



r=t 



Request 3 is now first in the queue and is given a lock on the 
resource. Because the request is for exclusive ownership, no other 
requests will be serviced. Once the process associated with request 3 
releases the lock, both request k and request 5 can be serviced 
because they both are for shared ownership. 
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6.3 PREPARING FOR THE ENQ/DEQ FACILITY 

Before using the ENQ/DEQ facility, the user must obtain an ENQ quota 
from the system administrator and must obtain the name of the resource 
desired, the type of protection required, and the level number 
associated with the resource. 

The ENQ quota indicates the total number of requests that can be 
outstanding for the user at any given time. Any request that would 
cause the quota to be exceeded results in an error. The user cannot 
use the ENQ facility if the quota is set to zero. 

The resource name has a meaning agreed upon by all users of the 
specific resource and serves as an identifier of the resource. The 
system makes no association between the resource name and the physical 
resource itself; it is the responsibility of the user's process to 
make that association. The system merely uses the resource name to 
process requests and handles different resource names as requests for 
different resources. 

The resource name has two parts. In most cases, the first part is the 
JFN of the file being accessed. Before using the ENQ facility, the 
user must initialize the file using the appropriate monitor calls 
{refer to Section 3«1)« The second part of the name is a modifier, 
which is either a pointer to a string or a 33~bit user code. The 
string uniquely identifies the resource to all users. The pointer can 
either be a standard byte pointer or be in the form 

-1,,ADR 

where ADR is the location of the left-justified ASCIZ text string. 
The 33-bit user code similarly identifies the resource by representing 
an item such as a record number or block number. The ENQ facility 
considers these modifiers as logical strings and does not check for 
cooperation among the users. Thus, users must be careful when 
assigning these modifiers to prevent the occurrence of two different 
modifiers referring to the same resource. 

The type of protection desired for the resource is indicated by the 
first part of the resource name. This part of the name can be one of 
four values. When the user specifies the JFN of the desired file, the 
file is subject to the standard access protection of the system. This 
is the most typical case. When the user specifies -1 instead of a 
JFN, it means that resources defined within a job are to be accessed 
only by processes of that job. Other jobs requesting resources of the 
same name are queued to a different resource. When the user specifies 
-2 instead of a JFN, it means that the resource can be accessed by any 
job on the system. A process must have bit SC%ENQ enabled in its 
capability word to specify this type of protection. If the user 
specifies -3 instead of a JFN, it means the same type of protection as 
that given when -2 is specified. However, this is reserved for the 
monitor and requires that the process have WHEEL or OPERATOR 
capability enabled. Quotas are not checked when -3 is given instead 
of a JFN. 
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In addition to specifying the resource name and type of protection, 
the user also assigns a level number to each resource. The use of 
level numbers prevents the occurrence of a deadly embrace situation: 
the situation where two or more processes are waiting for each to 
complete, but none of the processes can obtain a lock on the resource 
it needs for completion. This situation is represented by Figure 6-1. 



Process A Is 
Waiting for a 












Resource Process 
BHas. 




1 




, 




Process B Is 
Waiting for a 
Resource Process 
C Has. 


















Process C Is 
Waiting for a 










Resource Process 
A Has. 
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Figure 6-1: Deadly Embrace Situation 



Each process is in the queue waiting for the resource it needs, but no 
request is being serviced because the desired resources are 
unavai 1 able. 

The use of level numbers forces cooperating processes to order their 
use of resources by requiring that processes request resources in an 
ascending numerical order and that all processes assign the same level 
number to a specific resource. This means that the order in which 
resources are requested is the same for all processes and therefore, 
requests for the first resource will always precede requests for the 
second one. 

If both of the above requirements are not met, the process requesting 
the resource receives an error, unless the appropriate flag bit is set 
(refer to Section 6.4.1.2), and the request is not placed in the 
queue. Thus, instead of waiting for a resource it will never get, the 
process is informed immediately that the resource is not available. 
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6.i» USING THE ENQ/DEQ FACILITY 

There are three monitor calls available for the ENQ/DEQ facility: 
ENQ%, to request use of a resource; DEQ%, to release a lock on a 
resource; and ENQC%, to obtain information about the queues and to 
specify access to these queues. 



6.4.1 Requesting Use of a Resource 

The user issues the ENQ% monitor call to place a request in the queue 
associated with the desired resource. This call is used to specify 
the resource name, level number, and type of protection required. 

A single ENQ% monitor call can be used to request any number of 
resources. In fact, when desiring multiple resources, the user should 
request all of them in one call. This method of requesting resources 
guarantees that the user gets either none or all of the resources 
requested because the ENQ/DEQ facility never allocates only some of 
the resources specified in one call. Because all resources in a 
single call must be available at the same time, the first user 
requesting a resource (that is, the first user in the queue for the 
resource) may not be the first user obtaining it if other resources in 
the request are currently not available. 

A single call for multiple resources is not functionally the same as a 
series of single calls of those resources. In a single call, the 
entire request is rejected if an error is returned for one of the 
resources specified. In a series of single calls, each request that 
did not return an error will be queued. 

The ENQ% monitor call accepts two words of arguments in AC1 and AC2. 
The first word contains the code of the desired function, and the 
second contains the address of the argument block. Thus, 

AC1 : function code 

AC2: address of argument block 



6.4.1.1 ENQ% Functions - The functions that can be requested in the 
ENQ% call are described in Table 6-1. 
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Table 6-1: ENQ% Functions 

Code Symbol Meaning 



.ENQBL Queue the requests and block the 
process until all requested locks are 
acquired. This function returns an 
error code only if the ENQ% call is 
not correctly specified. 

•ENQAA Queue the requests and acquire the 
locks only if all requested resources 
are immediately available. If the 
resources are available, all will be 
allocated to the process. If any one 
of the resources is not available, no 
requests are queued, no locks are 
acquired, and an error code is 
returned in AC1 . 

.ENQSI Queue the requests for all specified 
resources. If all resources are 
available, this function is identical 
to the .ENQBL function. If all 
resources are not immediately 
available, the requests are queued, 
and a software interrupt is generated 
when all requested resources have been 
given to the process. 
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Table 6-1: ENQ% Functions (Cont.) 



Code 



Symbol 



Mean i ng 



.ENQMA 



Change the ownership access of a 
previously-queued request (refer to 
bit EN%SHR below). The access for 
each lock in this request is compared 
with the access for each lock in the 
request already queued. No action is 
taken if the two accesses are the 
same. If the access in this request 
is shared and the access in the 
previous request is exclusive, the 
ownership access is changed to shared 
access. Otherwise, an error is 
returned if: 



1. The process tries to change 
the ownership access from 
shared to exclusive. If this 
is desired, the process should 
issue a DEQ% monitor call for 
the shared request and then 
issue another ENQ% monitor 
call for exclusive ownership. 

2. Any one of the specified locks 
does not have a pending 
request. 

3. Any one of the specified locks 
is a pooled resource (refer to 
Section 6.4.1.2) . 

Each lock specified is checked, and 
the access is changed for all locks 
that were correctly given. On 
receiving an error, the process 
should issue the ENQC% monitor call 
to determine the current state of 
each lock (refer to Section 6.4.3)- 
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6. k. 1.2 ENQ% Argument Block - The format of the argument block is 
described in Table 6-2. 



Table 6-2: ENQ% Argument Block 



Word 



Symbol 



Meaning 



.ENQLN Number of locks being requested in the left 
half, and length of argument block (including 
this word) in the right half. 

.ENQID Number of software interrupt channel in the 
left half, and request ID in the right half. 

.ENQLV Flags and level number in the left half, and 
JFN, -1, -2 or -3 (refer to Section 6.3) in 
the right half. 

.ENQUC Pointer to string or 5B2+33"bit user code 
(refer to Section 6.3) • 

.ENQRS Number of resources in the pool in the left 
half, and number of resources requested in 
the right half. 

.ENQM5 Address of a resource mask block. 



Words .ENQLV, .ENQUC, and .ENQRS (words 2 through k) are repeated for 
each lock being requested. These three words are called the lock 
speci f ication. 

Software Interrupts 

The software interrupt system is used in conjunction with the .ENQSI 
function (refer to Section 6.^t. 1.1). If all locks are not available 
when the user requests them, the .ENQSI function causes a software 
interrupt to be generated when the locks become available. The user 
specifies the software channel on which to receive the interrupt by 
placing the channel number in the left half of word .ENQID in the 
argument block. 
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When the user is waiting for more than one lock to become available, 
he will receive an interrupt when the last lock is available. If he 
desires to be informed as each lock becomes available, he can assign 
the locks to separate channels by issuing multiple ENQ% calls. The 
availability of each lock will then be indicated by the occurrence of 
an interrupt on each channel. 

When the user requests the .ENQSI function, he must initialize the 
interrupt system first or else an interrupt will not be generated when 
the locks become available (refer to Chapter k) . 

Request ID 

The 18-bit request ID is currently not used by the system, but is 
stored for use by the process. Thus, the process can supply an ID to 
use as identification for the request. This ID is useful on the 
| .DEQID function of the DEQ% monitor call (refer to Section 6.4.2.1). 

Flags and Level Numbers 

| Table 6-3 describes the flags that can be used in the left half of the 
j first word of each lock specification (.ENQLV) . 
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| Table 6-3: Lock Specification Flags 



Bit 



Symbol 



Meaning 



EN%5HR 



Ownership for this resource is to be 
shared. If this bit is not on, 
ownership for this resource is to be 
exclusive. 



EN%EiLN 



Ignore the level number associated 
with this resource. If this bit is 
set, sequencing errors in level 
numbers are not considered fatal, and 
execution of the call continues. 



On successful completion of the call, 
ACT contains either an error code if a 
sequencing error occurred, or zero if 
a sequencing error did not occur. 

WARNING 



1 2 


EN%NST 


i 3 


EN%LTL 


1 k-8 




9-17 


EN%LVL 



A deadly embrace situation may 
occur when level numbers are 
not used. Use of these 
numbers guarantees that such a 
situation cannot arise; for 
this reason bit EN%BLN should 
not be set. 



this lock to be 



Al low ownership of 
nested. 

Allow a long-term lock on this 
resource. 

Reserved for Digital. 

Level number associated with this 
resource. This number is specified by 
the user and must be agreed upon by 
al 1 users of the resource, 
to eliminate a deadly 
situation, users must 
resources in numerically 
order . 



I n order 

embrace 

request 

increasing 
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The request is not queued, and an error is given, if ENfcBLN is not set 
and 

1. The user requests a resource with a level number less than or 
equal to the highest numbered resource he has requested so 
far . 

2. The level number of this request does not match the level 
number supplied in previous requests for this resource. 

Pooled Resources 

Word .ENQRS of each lock specification is used to allocate multiple 
copies from a pool of identical resources. Bit EN%SHR, indicating 
shared ownership, is meaningless for pooled resources because each 
resource in the pool can be owned by only one process at a time. A 
process can own one or more resources in the pool; however, it cannot 
own more than there are in the pool or more than there are unowned in 
the pool . 

The left half of word .ENQRS contains the total number of resources 
existing in the pool. This number is previously agreed upon by all 
users of the pooled resource. The first user who requests the 
resource sets this number, and all subsequent requests must specify 
the same number or an error is given. 

The right half of word .ENQRS contains the number of resources being 
requested by this process. This number must be greater than zero if a 
pool of resources exists and cannot be greater than the number in the 
left half. This means that if a pool of resources exists, the user 
must request at least one resource, but cannot request more than are 
i n the pool . 

Once the number of pooled resources is determined, the resources are 
allocated until the pool is depleted or until a request specifies more 
resources than are currently available. In the latter case, the user 
making the request is not given any resources until his entire request 
can be satisfied. Subsequent requests from other users are not 
granted until this request is satisfied even though there may be 
enough resources to satisfy these subsequent requests. As users 
release their resources, the resources are returned to the pool. When 
all resources have been returned, they cease to exist, and the next 
request completely redefines the number of resources in the new pool. 
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The system assumes that the resource is in a pool if the left half of 
word .ENQRS of the lock specification is nonzero. Thus the user 
should set the left half to zero if only one resource of a specific 
type exists. If this is the case, then the right half of this word is 
a number defining the group of users who can simultaneously share the 
resource. This means that when the resource is allocated to a user 
for shared ownership, only other users in the same group will be 
allowed access to the resource. The use of sharer groups restricts 
access to a resource to a set of processes smaller than the set for 
shared ownership (which is sharer group 0) but larger than the set for 
exclusive ownership. (Refer to Section 6.5 for more information on 
sharer groups) . 



6„4.2 Releasing a Resource 

The user issues the DEQ% monitor call to remove a request from the 

queue associated with a resource. The request is removed whether or 

not the user actually owns a lock on the resource or is only waiting 
in the queue for the resource. 

The DEQ% monitor call can be used to remove any number of requests 
from the queues. If one of the requests cannot be removed, the 
dequeueing procedure continues until all lock specifications have been 
processed. An error code is then returned for the last request found 
that could not be dequeued. The process can then execute the ENQC% 
call (refer to Section 6.4.3) to determine the status of each lock. 
Thus, unlike the operation of the ENQ% call, the DEQ% call will 
dequeue as many resources as it can, even if an error is returned for 
one of the lock specifications in the argument block. However, when a 
user attempts to dequeue more pooled resources than he originally 
allocated, an error code is returned and none of the resources are 
dequeued. 

The DEQ% monitor call accepts two words of arguments in AC1 and AC2. 
The first word contains the code for the desired function, and the 
second word contains the address of the argument block. Thus, 

AC1 : f unct i on code 

AC2: address of argument block 
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6. it. 2.1 DEQ% Functions - The DEQ% functions are described in Table 
6-if. 



Table 6-4: DEQ% Functions 



Code Symbol Meaning 



.DEQDR Remove the specified requests from the queues. 
This function is the only one that requires an 
argument block. 

.DEQDA Remove all requests for this process from the 
queues. This action is taken on a RESET 
monitor call. An error code is returned if 
this process has not requested any resources 
(that is, if this process has not issued an 
ENQ%) . 

•DEQID Remove all requests that correspond to the 
specified request identifier. When this 
function is specified, the user must place the 
18-bit request ID in AC2 on the DEQ% call. 
This function allows the user to release a 
class of locks in one call without itemizing 
each lock in an argument block. The function 
should be used when dequeue ing in one call the 
same locks that were enqueued in one call. 
For example, with this function the user can 
specify the ID to be the same as the JFN used 
in the ENQ% call and thus remove all locks to 
that file at once. 
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6. It. 2. 2 DEQ% Argument Block - The format of the argument block for 
function .DEQDR is described in Table 6-5. 



Table 6-5: DEQ% Argument Block 



Word 



Symbol 



Meani ng 



.ENQLN Number of locks being requested in the left 
half, and length of argument block 
(including this word) in the right half. 

•ENQID Number of software interrupt channel in the 
left half, and request ID in the right 
half. 

•ENQLV Flags and level number in the left half, 
and JFN, -1, -2 or -3 (refer to Section 
6.3) in the right half. 

.ENQUC Pointer to string or 5B2+33-bit user code 
(refer to Section 6.3) . 

.ENQRS Number of resources in the pool in the left 
half, and number of resources requested in 
the right half. 

.ENQMS Address of a resource mask block. 



Words .ENQLV, .ENQUC, and .ENQRS (words 2 through k) are repeated for 
each request being dequeued. These three words are called the lock 
speci f i cat ion. 
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6. it. 3 Obtaining Information About Resources 

The user issues the ENQC% monitor call to obtain information about the 
current status of the given resources. This call can also be used by 
privileged users to perform various utility functions on the queue 
structure. The format of the ENQC% call is different for these two 
uses. (Refer to the TOPS-20 Monitor Cal Is Reference Manual for the 
explanation of the privileged use of the ENQC% call.) 

The ENQC% monitor call accepts three words of arguments in AC1 through 
AC3: 

AC1: function code (.ENQCS) 

AC2: address of argument block 

AC3: address of area to receive status information 

The format of the argument block is identical to the format of the 
ENQ% and DEQ% argument blocks. The area in which the status is to be 
returned should be three times as long as the number of locks 
specified in the argument block. 

On successful execution of the ENQC% call, the current status of each 
lock specified is returned as a three-word entry. This three-word 
entry has the following format. 



Flag bits indicating status of lock 
36-bit time stamp 
Reserved ! Request ID 
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Table 6-6 describes the flag bits that can be used in a ENQC% cal 
Table 6-6: ENQC% Flag Bits 

Bit Symbol Meaning 



EN%QCE An error has occurred in the 

corresponding lock request. Bits 
18-35 contain the appropriate error 
code. 

1 EN%QC0 The process issuing the ENQC% call is 

the owner of this lock. 

2 EN%QCQ The process issuing the ENQC% call is 

in the queue waiting for this 
resource. This bit will be on when 
EN%QC0 is on because a request remains 
in the queue until a DEQ% call is 
given. 

3 EN&QCX The lock has been allocated for 

exclusive ownership. When this bit is 
off, there is no way of determining 
the number of sharers of the resource. 

h EN%QCB The process issuing the ENQC% call is 

in the queue waiting for exclusive 
ownership to the resource. This bit 
will be off if EN%QCQ is off. 

Reserved for Digital. 

The level number of the resource. 

The number of the job that owns the 
lock. For locks with shared 
ownership, this value will be the job 
number of one of the owners. However, 
this value will be the current job's 
number if the current job is one of 
the owners. If this lock is not 
owned, the value is -1. 

If EN%QCE is on, this field contains 
the appropriate error code. 
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EN%LVL 


18-35 


EN%J0B 
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The 36-bit time stamp indicates the last time a process locked the 
resource. The time is in the universal date-time standard. If no one 
currently has a lock on the resource, this word is zero. 

The request ID returned in the right half of the third word is either 
the request ID of the current process if that process is in the queue 
or the request ID of the owner of the lock. 



6.5 SHARER GROUPS 

Processes can specify the sharing of resources by using sharer group 
numbers (refer to Section 6-4.1.2) . The use of sharer groups 
restricts the ownership for a resource to a set of processes smaller 
than the set for shared ownership but larger than the set for 
exclusive ownership. 

Sharer group number is used to indicate the group of all cooperating 
processes of the resource. This group number is assumed when no group 
is specified in the ENQ% call. To restrict use of the resource, a 
group number other than must be explicitly specified in the call. 

Consider the following example. The resource is the WRITE operation 
on a file. There are four types of uses of this resource as shown in 
Figure 6-2. 



> \. Process' Own Use of 
-vthe Resource 

Other ^\ 
Process' Use \^ 

of the Resource ^*w 


Write 


Not Allowed 
to Write 


Write 


1 

Shared, Group 


2 

No Need to Use 
ENQ/DEQ 


Not Allowed 
to Write 


3 
Exclusive 


4 

Shared, Group 1 



Figure 6-2: Use of Sharer Groups 
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In block 1 of the figure, the process owning the lock wishes to allow 
all cooperating processes to also lock the resource (that is, to 
perform the WRITE operation). Therefore, in the ENQ% call, the 
process specifies the resource can be locked by all cooperating 
processes. In block 2 of the figure, the process does not plan on 
locking the resource and does not care if other processes lock it. 
Thus, there is no need for the process to use the ENQ/DEQ facility. 
In block 3 of the figure, the process desires to lock the resource 
exclusively and does not want other processes to lock it. Thus, the 
process obtains exclusive ownership for the resource. In block k of 
the figure, the process does not want to lock the resource immediately 
but also does not want other processes to lock it because it soon 
plans to request a lock on the resource. If the process were the only 
one requesting this type of use, exclusive ownership would be 
sufficient, because the resource would be unavailable to others as 
long as the process owned the lock. However, if other processes 
desire this same type of use, exclusive ownership is not sufficient, 
because once one process releases the lock, another process with a 
different type of use could obtain its own lock. Thus, in this 
example, sharer group 1 is defined to include all processes with the 
same type of use (that is, all processes who do not want to lock the 
resource immediately but also do not want other processes to lock it). 
This el imates the problem of another user obtaining the resource for a 
different type of use. 

Sharer group should be sufficient for most uses of the ENQ/DEQ 
facility. Additional groups should only be needed in those situations 
where a subset of the cooperating processes must have a specific use 
of a resource, as in the above example. 



6.6 AVOIDING DEADLY EMBRACES 

Processes can interact in many undesirable ways if improper 
communication occurs among the processes or if resources are 
incorrectly shared. An example of one undesirable situation is the 
occurrence of a deadly embrace: when two processes are waiting for 
each other to complete but neither one can gain access to the resource 
it needs for completion. This situation can be avoided when processes 
consider the following guidelines. 

1. Processes should request resources at the time they need 
them. If possible, processes should request resources one at 
a time and release each resource before requesting the next 
one. 

2. Processes should request shared ownership whenever possible. 
However, the process should not request shared ownership if 
it plans on modifying the resource. 
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3. When a process needs more than one resource, it should 
request these resources in one ENQ% call instead of multiple 
calls for each resource. The process should also release the 
entire set of resources at once with a single DEQ% call. 

k. When the use of one resource depends on the use of a second 
one, the process should define the two resources as one in 
the ENQ% and DEQ% calls. However, there is no protection of 
the resources if they are also requested separately. 

5. Occasionally processes use a set of resources and require a 
lock on the second resource while retaining the lock on the 
first. In this case, the order in which the locks are 
obtained should be the same for all users of the set of 
resources. The same ordering of locks is accomplished by the 
processes assigning level numbers to each resource. The 
requirements that processes request resources in ascending 
numerical order and that all processes use the same level 
number for a specific resource ensure that a deadly embrace 
situation will not occur. 
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CHAPTER 7 
INTER-PROCESS COMMUNICATION FACILITY 



7.1 OVERVIEW 

The Inter-Process Communication Facility (IPCF) allows communication 
among jobs and system processes. This communication occurs when 
processes send and receive information in the form of packets. Each 
sender and receiver has a Process ID (PID) assigned to it for 
identification purposes. 

When the sender sends a packet of information to another process, the 
packet is placed into the receiver's input queue. The packet remains 
in the queue until the receiver checks the queue and retrieves the 
packet. Instead of periodically checking its input queue, the 
receiver can enable the software interrupt system (refer to Chapter h) 
to generate an interrupt when a packet is placed in its input queue. 

The <SYSTEM>INFO process is the information center for the 
Inter-Process Communication Facility. This process performs system 
functions related to PIDs and names, and any process can request these 
functions by sending <SYSTEM>INFO a packet. 



7 . 2 QUOTAS 

Before using IPCF, the user must acquire the ability to use IPCF 
privileges from the system administrator: a send packet quota and a 
receive packet quota. These quotas designate, on a per process basis, 
the number of sends and receives that can be outstanding at any one 
time. For example, if the process has a send quota of two and it has 
sent two packets, it cannot send any more until at least one packet 
has been retrieved by its receiver. A send packet quota of two and a 
receive packet quota of five are assumed as the standard quotas. If 
these quotas are zero, the process cannot use IPCF. 
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7.3 PACKETS 



Information is transferred in the form of packets. Each packet is 
divided into two portions: a packet descriptor block of four to six 
words and a packet data block the length of the message. The format 
of the packet is shown in Figure 7-1. 



Packet Descriptor Block 






.IPCFL 
.IPCFS 
.IPCFR 
.IPCFP 

.IPCFD 

.IPCFC 
.IPCSD 
. IPCAS 
.IPCLL 



flags 
PID of sender 



PID of receiver 



length of message ! address of message 
n ! ADR 



sender's connected 
directory 



sender's logged in 
di rectory 



enabled capabilities of sender 
connected directory of sender 






account string of sender 
logical location of sender 



Packet Data Block 



ADR 






message word 1 






!==« 



message word n 



Figure 7-1 : I PCF Packet 
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7.3.1 Flags 

There are two types of flags that can be set in word .IPCFL of the 
packet descriptor block. The flags in the left half of the word are 
instructions to IPCF for packet communication, and the flags in the 
right half are descriptions of the data message. The flags in the 
right half are returned as part of the associated variable (refer to 
Section J.k.2). The packet descriptor block flags are described in 
Table 7-1. 



Table 7-\t Packet Descriptor Block Flags 



Bit 



Symbol 



Meaning 



IP%CFB 



IP%CFS 



IP%CFR 



Do not block the process if there are no 
messages in the queue. If this bit is on, the 
process receives an error if there are no 
messages. 

Use the PID obtained from the address in word 
.IPCFS of the packet descriptor block as the 
sender's PID. 

Use the PID obtained from the address in word 
•IPCFR of the packet descriptor block as the 
receiver's PID. 



3 

k 



IP%CF0 
I P%TTL 



P%CPD 



! P% JWP 



Allow the process one send above the send quota. 
(The standard send quota is two.) 

Truncate the message if it is longer than the 
area reserved for it in the packet data block. 
If this bit is not on, the process receives an 
error if the message is too long. 



Create a PID to use as the sender 
PID created is returned in word 
packet descriptor block. 



s PID. The 
.IPCFS of the 



Make the PID created be permanent until the job 
logs out (if both bits I P%CPD and I P%JWP are 
on). Make the PID created be temporary until 
the process executes a RESET% monitor call (if 
bit IP%CPD is on and bit I P%JWP is not on). If 
bit IP%CPD is not on, bit I P%JWP is ignored. 
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Table 7-1: Packet Descriptor Block Flags (Cont.) 



Bit Symbol Meaning 

7 IP%N0A Do not allow other processes to use the PID 

created when bit IP%CPD is on. If bit IP%CPD is 
not on, bit I P%N0A is ignored. 

8-17 Reserved for Digital. 

18 IP%CFP The packet is privileged. This bit can be set 

only by a process with WHEEL capability enabled. 
Refer to the TOPS-20 Moni tor Cal Is Reference 
Manual for a description of this bit. 

19 IP%CFV The packet is a page of 512 (decimal) words of 

data. 

20 IP%CFZ A zero- length message was sent. 

21 Reserved for Digital. 

22 IP%EPN Page number in word .IPCFP of the packet 

descriptor block is 18 bits long 

23 Reserved for Digital. 

24-29 IP%CFE Field for error code returned from <SYSTEM> 

INFO. 

Code Symbol Meaning 

15 .IPCPI insufficient privileges 

16 .IPCUF invalid function 

66 .IPCKM PID has been deleted 

67 .IPCSN <SYSTEM> INFO needs name 

72 .IPCFF <SYSTEM>INFO free space exhausted 

7k .IPCBP PID has no name or is invalid 

75 .IPCDN duplicate name has been specified 

76 . I PCNN unknown name has been specified 

77 . IPCEN invalid name has been specified 
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Table J-]: Packet Descriptor Block Flags (Cont.) 



Bit Symbol Meaning 



30-32 IP%CFC System and sender code. This code can be set 

only by a process with WHEEL capability enabled, 
but the monitor will return the code so a 
nonpr ivi leged process can examine it. 

Code Symbol Meaning 

1 .IPCCC Sent by <SYSTEM>IPCF 

2 .IPCCF Sent by system-wide <SYSTEM>INFO 

3 .IPCCP Sent by receiver's <SYSTEM>INFO 

k .IPCCG Sent by monitor for QUEUE% JSYS 

33-35 IP%CFM Field for special messages. This code can be 

set only by a process with WHEEL capability 
enabled, but the monitor will return the code so 
that a nonpr ivi leged process can examine it. 

Code Symbol Meaning 

1 .IPCFN Process 1 input queue contains a 
packet that could not be delivered 
to intended PID. 
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7.3.2 PIDs 

Any process that wants to send or receive a packet must obtain a PID. 
The process can obtain a PID by sending a packet to <SYSTEM>INFO 
requesting that a PID be assigned. The process must also include a 
symbolic name that is to be associated with the assigned PID. 

The symbolic name can be a maximum of 29 characters and can contain 
any characters as long as it is terminated by a zero word. There 
should be mutual understanding among processes as to the symbolic 
names used in order to initiate communication. Once the name is 
defined, any process referring to that name must specify it exactly 
character for character. 

Before a process can send a packet, it must know the receiver's 

symbolic name or PID. If only the receiver's name is known, the 

sender must ask <SYSTEM>INFO for the PID associated with the name, 
since all communication is via PIDs. 

The association between a PID and a name is broken: 

1. On a RESET% monitor call. 

2. When the process is killed or the job logs off the system. 

3- When a request to disassociate the PID from the name is made 
to <SYSTEM>INFO. 

<SYSTEM>INFO will not allow a name already associated with a PID to be 
assigned again unless the owner of the name makes the request. Nor 
will <SYSTEM>INFO assign a PID once it has been used. This action 
protects against messages being sent to the wrong receiver by 
accident. 

The PIDs of the sender and the receiver are indicated by words .IIPCFS 
and .IPCFR, respectively, of the packet descriptor block. 



7.3-3 Length And Address Of Packet Data Block 

Word .IPCFP of the packet descriptor block contains the length and the 
beginning address of the message. The length specified is one of two 
types, depending on the type of message (refer to Section 7.3.5). If 
the message is a short-form message, the length is the actual word 
length of the message. If the message is a long-form message, the 
length is 1000 (octal) words, that is, one page. 

The address specified is either an address or a page number, depending 
on the type of message (refer to Section 7-3-5) • When a message is 
sent, it is taken from this address. When a message is received, it 
is placed in this address. 
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"/. 3- A Directories and Capabilities 

Words .IPCFD and .IPCFC describe the sender at the time the message 
was sent and are used by the receiver to validate messages sent to it. 
These two words are not used when a message is sent, and if the sender 
of the packet supplies them, they are ignored. However, when a 
message is received, if the receiver of the packet has reserved space 
for these words in the packet descriptor block, the system supplies 
the appropriate values of the sender of the packet. The receiver of 
the packet does not have to reserve these words if it is not 
interested in knowing the sender's directories and capabilities. 



7.3.5 Packet Data Block 

The packet data block contains the message being sent or received. 
The message can be either a short-form message or a long-form message. 

A short-form message is one to n words long, where n is defined by the 
installation. (Usually, n is assumed to be 10 words.) When a 
short-form message is sent or received, word .IPCFP of the packet 
descriptor block contains the actual word length of the message in the 
left half and the address of the first word of the message in the 
right half. A process always uses the short form when sending 
messages to <SYSTEM>INF0. 

A long-form message is one page in length (1000 octal words). When a 
long-form message is sent or received, word .IPCFP of the packet 
descriptor block contains 1000 (octal) in the left half and the page 
number of the message in the right half. To send and receive a 
long-form message, both the sender and receiver must have bit IP%CFV 
(bit 19) set in the first word of the packet descriptor block, or else 
an error code is returned. 



/.it SENDING AND RECEIVING MESSAGES 

To send a message, the sending process must set up the first four 
words of the packet descriptor block. The process then executes the 
MSEND% monitor call. After execution of this call, the packet is sent 
to the intended receiver's input queue. 

To receive a message, the receiving process must also set up the first 
four words of the packet descriptor block. The last two words for the 
directories and capabilities of the sender can be supplied, and the 
system will fill in the appropriate values. The process then executes 
the MRECV% monitor call. After execution of this call, a packet is 
retrieved from the receiver's input queue. The input queue is emptied 
on a f i rst-message- in, first-message-out basis. 
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7.^.1 Sending a Packet 

The MSEND% monitor call is used to send a message via IPCF. Messages 
are in the form of packets of information and can be sent to a 
specified PID or to the system process <SYSTEM>INFO. Refer to Section 
7.5 for information on sending messages to <SYSTEM>INFO. 

The MSEND% call accepts two words of arguments. The length of the 
packet descriptor block is given in AC1, and the beginning address of 
the packet descriptor block is given in AC2. Thus, 

AC1: length of packet descriptor block. The length cannot be 
less than k . 

AC2: address of packet descriptor block 

The packet descriptor block consists of the following four words: 

.IPCFL Flags 
.IPCFS Sender's PID 
. IPCFR Receiver's PID 

.IPCFP Pointer to packet data block containing the 
message being sent. 



Refer to Section 7-3 for the details on the packet descriptor and 
packet data blocks. 

The flags that are meaningful when sending a packet are described in 
Table 7~2. Refer to Table 7-1 for the complete list of flag bits. 
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Table 7-2: Flags Meaningful on a MSEND% Call 



Bit 



Symbol 



Meaning 



IP%CFB Do not block process if no messages in queue; 
if set, error return if no messages. 

I P%CFS The sender's PID is given in word .IPCFS of 
the packet descriptor block. 

IP%CFR The receiver's PID is given in word .IPCFR of 
the packet descriptor block. 

IP%CF0 Allow the sender to send one message above its 
send quota. 

IPfcTTL Truncate message if larger than space 
reserved. 

IP%CPD Create a PID for the sender and return it in 
word .IPCFS of the packet descriptor block. 
The PID created is to be permanent and useable 
by other processes according to the setting of 
bits IP%JWP and IP%N0A. 

IP%JWP The PID created is to be job wide and 
permanent until the job logs out. If this bit 
is not on, the PID created is to be temporary 
until the process executes the RESET monitor 
call. 

IP%N0A The PID created is not to be used by other 
processes. 

IP%CFP The message being sent is privileged (refer to 
the T0PS-20 Moni tor Cal Is Reference Manual ) . 

IP%CFV The message being sent is a long-form message 
(that is, a page). The page the message is 
being sent to cannot be a shared page; it must 
be a private page. 

IP%EPN Page number in word .IPCFP of the packet 
descriptor block is 18 bits long. 



7 

18 

19 



22 
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When bit IP%CFS is on in the flag word, the sender's PID is taken from 
word .IPCFS of the packet descriptor block. This word is zero if bit 
IP%CPD is on in the flag word, indicating that a PID is to be created 
for the sender. In this case, the PID created is returned in word 
.IPCFS. 

When bit IP%CFR is on in the flag word, the receiver's PID is taken 
from word .IPCFR of the packet descriptor block. If this word is 0, 
then the receiver of the message is <SYSTEM>INF0. Refer to Section 
7-5 for information on sending messages to <SYSTEM>INF0. 

On successful execution of the MSEND% monitor call, the packet is sent 
to the receiver's input queue. Word .IPCFS of the packet descriptor 
block is updated with the sender's PID. Execution of the user's 
program continues at the second location after the MSEND% call. 
(MSEND%) 

If execution of the MSEND% call is not successful, the message is not 
sent, and an error code is returned in AC1. The execution of the 
user's program continues at the instruction following the MSEND% call. 



7.^.2 Receiving a Packet 

The MRECV% monitor call is used to retrieve a message from the 

process' input queue. Before a process can retrieve a message, it 

must know if the message is a long-form message and also must set up a 
packet descriptor block. 

The MRECV% monitor call accepts two words of arguments. The length of 
the packet descriptor block is given in AC1, and the beginning address 
of the packet descriptor block is given in AC2. Thus, 

AC1: length of packet descriptor block. The length cannot be 
less than k. 

AC2: address of packet descriptor block 
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The packet descriptor block can consist of the following nine words. 
The last five words are optional, and if supplied by the receiver, the 
values of the sender will be filled in by the system. 



IPCFL 
IPCFS 
IPCFR 
IPCFP 

IPCFD 
IPCFC 
I PCSD 
IPCAS 
IPCLL 



F lags 

Sender's PID 

Receiver's PID 

Pointer to packet data block where the message is 

to be placed. 

Connected and logged- in directories of the sender 

Enabled capabilities of the sender. 

Number of sender's connected directory. 

Account string of sender. 

Byte pointer for destination of sender's node. 



Refer to Section 7«3 for the details 
packet data blocks. 



on the packet descriptor and 



| The flags that are meaningful when receiving a packet are described in 
j Table 7 - 3- Refer to Table 7 - l for the complete list of flag bits. 
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Table 7"3: Flags Meaningful on a MRECV% Call 



Bit 



Symbol 



Meaning 



P%CFB 



I 1 



I 3 
I 

1* 



P%CFS 
P%CFR 
P%CF0 
P%TTL 



1 5 


IP%CPD 


! * 


IP%JWP 


i 7 


IP%N0A 


i 18 


IP%CFP 



If there are no packets in the receiver's 
input queue, do not block the process and 
return an error code if the queue is empty. 
If this bit is not on, the process waits until 
a packet arrives, if the queue is empty. 

Use PID referenced in word .IPCFS as sender's 
PID. 

The receiver's PID is given in word .IPCFR of 
the packet descriptor block. 

Allow one send request above quota. (Default 
send quota is 2.) 

Truncate the message if it is larger than the 
space reserved for it in the packet data 
block. If this bit is not on and the message 
is too large, an error code is returned and no 
message is received. 

Create PID for sender and return in word 
.IPCFS. 

Make created PID job wide (ignored unless 
IP%CPD set) . 

Do not allow other processes to use created 
PID (ignored unless IP%CPD set). 

Packet is privileged (requires IPCF capability 
enabled) . 



19 



22 



P%CFV The message is expected to be a long-form 
message (that is, a page). The page the 
message is being stored into cannot be a 
shared page; it must be a private page. 

P%EPN Page number in word .IPCFP of the packet 
descriptor block is 18 bits long. 
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The information in word .IPCFS is not supplied by the receiver when 
the MRECV% call is executed. The system fills in the PID of the 
sender of the packet when the packet is retrieved. 

Word .IPCFR is supplied by the receiver. If bit IP%CFR is on in the 
flag word, then the PID receiving the packet is taken from word .IPCFR 
of the packet descriptor block. If bit IP%CFR is not on in the flag 
word, then word .IPCFR contains either -1, to receive a packet for any 
PID belonging to this process, or -2, to receive a packet for any PID 
belonging to this job. When -1 or -2 is given, packets are not 
received in any particular order except that packets from a specific 
PID are received in the order in which they were sent. Any other 
values in this word cause an error code to be returned. 

The information in words .IPCFD and .IPCFC is also not supplied by the 
receiver. If these two words have been specified by the receiver, the 
system fills in the information when the packet is retrieved. Word 
.IPCFD contains the sender's connected directory in the left half and 
the sender's logged-in directory in the right half. Word .IPCFC 
contains the enabled capabilities of the sender. These words describe 
the sender at the time the message was sent. 

On successful execution of the MRECV% monitor call, the packet is 
retrieved and placed into the packet data block as indicated by word 
.IPCFP of the packet descriptor block. AC1 contains the length of the 
next packet in the queue in the left half and flags from the next 
packet in the right half (see below). This word returned in AC! is 
called the associated variable of the next packet in the queue. If 
there is not another packet in the queue, AC1 contains zero. 
Execution of the user's program continues at the second instruction 
after the MRECV% cal 1 . 

The flags returned in the right half of AC1 on successful execution of 
the MRECV% monitor call are described in Table J-h. 
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| Table J-hi MRECV% Return Bits 
I 



Bit Symbol Meaning 



30-32 IP%CFC System and sender code, set only by a 

privileged process. The packet was sent by 
<SYSTEM>IPCF if the code is l(.IPCCC). The 
packet was sent by the system-wide 
<SYSTEM>INFO if the code is 2 (. IPCCF) . The 
packet was sent by the receiver's 
<SYSTEM>INFO if the code is 3 (. I PCCP) . 

33-35 IP%CFM Field for return of special messages. If 

the field contains l(.IPCFN), then the 
process' input queue contains a packet that 
was sent to another PID, but was returned 
to the sender because it could not be 
del ivered. 



If execution of the MRECV% call is not successful, a packet is not 
retrieved, and an error code is returned in AC1. The execution of the 
user's program continues at the instruction following the MRECV% call. 



7.5 SENDING MESSAGES TO <SYSTEM>INFO 

The <SYSTEM>INFO process is the central information utility for IPCF. 
It performs functions associated with names and PIDs, such as, 
assigning a PID or a name or returning a name associated with a PID. 

A process can request functions to be performed by <SYSTEM>INFO by 
executing the MSEND% monitor call (refer to Section l.k. 1) . The 
message portion of the packet (that is, the packet data block) sent to 
<SYSTEM>1NF0 contains the request being made. In other words, the 
total request to <SYSTEM>INF0 is a packet consisting of a packet 
descriptor block and a packet data block containing the request. 
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Packet Descriptor Block 



| SSS5SSSSSSSS 

Packet Data Block 



flag word ! 

! 

sender's PID ! 
_ j 

! 

1 

pointer to request ! 



code 



i 



function 



PID 
function argument 



= ! 



Refer to Section T.k.] for the descriptions of the words in the packet 
descriptor block. The receiver's PID (word .IPCFR) is when sending 
a packet to <SYSTEM>I NFO. 



7-5.1 Format of <SYSTEM>INFO Requests 

I As mentioned previously, the packet data block (that is, the 
portion) of the packet contains the request to <SYSTEM>INFO. 



message 



The first word (word .IPC 10) contains a user-defined code in the left 
half and the function being requested in the right half. The 
user-defined code is used to associate the response from <SYSTEM>INFO 
with the correct request. The functions that the process can request 
of <SYSTEM>INFO are described in Table 7"5- 
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The second word (word .IPCIl) contains a PID associated with a process 
that is to receive a duplicate of any response from <SYSTEM>INFO. If 
this word is zero, the response from <SYSTEM>INFO is sent only to the 
process making the request. 

The third word (word .IPC 1 2) contains the argument for the function 
specified in the right half of word . I PC 1 . The argument is different 
depending on the function being requested. The arguments for the 
functions are described in Table 7 _ 5- 



Table 7-5: <SYSTEM>INFO Functions and Arguments 



Function Argument 



Meaning 



IPCIW 



name 



Return the PID associated with the 
given name (refer to Section 7.3-2 for 
the description of the name). 



I PCI G 



PID 



Return the name 
given PID. 



associated with the 



IPCI 



name in Assign the given name to the PID 
ASCIZ associated with the process making the 
request. The PID is permanent if 
IP%JWP was set in the flag word when 
the PID was originally created (refer 
to Table 7"D • 



I PC I J 



name i n 
ASCIZ 



Identical to .IPCIl function. 
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7.f>.2 Format of <SYSTEM>INFO Responses 

Responses from <SYSTEM>INFO are in the form of a packet sent to the 
process that made the request. A copy of the response is sent to the 
PID given in word - I PC I 1 , if any. 

The message portion (that is, the packet data block) of the packet 
contains the response from <SYSTEM>I NFO. The format of this response 
i s 



I: 



code 



function 



response 
response 



■-! 



The first word (word .IPC 10) contains the user-defined code in the 
left half and the function that was requested in the right half. 
These values are copied from the values given in the request. 

The second and third words (words .IPCM and .IPC 1 2) contain the 
response from the function requested of <SYSTEM>INF0. The response is 
different depending on the function requested. The responses from the 
functions are described in Table J-6. 



Table 7-6: <SYSTEM>INF0 Responses 



Function Requested 



Response 



.IPCIW 



The PID associated with the name given in 
the request is returned in word .IPCM. 



IPCIG 



The name associated with the PID given in 
the request is returned in word .IPCM. 



PCI I 



No response is returned. 
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7-6 PERFORMING IPCF UTILITY FUNCTIONS 

A process can request various functions to be performed by executing 
the MUTIL% monitor call. Some of these functions are enabling and 
disabling PIDs, creating and deleting PIDs, and returning quotas. 
Several of the functions that can be requested are privileged 
functions. These are described in the TOPS-20 Monitor Cal Is Reference 
Manual . 

The MUTIL% monitor call accepts two words of argument. The length of 
the argument block is given in AC1, and the beginning address of the 
argument block is given in AC2. 

The argument block has the following format: 



function code 



! argument for function ! 

" ! 

! argument for function ! 

The arguments are different, depending on the function being 
requested. Any values resulting from the function requested are 
returned in the argument block, starting at the second word. 

Table 7-7 describes the functions that can be requested, the arguments 
for the functions, and the values returned from the functions. 
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Table 7~7: MUTIL% Functions 



Function 



Meaning 



•MUENB 



Allow the PID given to receive packets. If the 
process executing the call is not the owner of 
the PID, the process must be privileged. 



Argument 
PID 

Value Returned 
None 



.MUDIS 



Disable the PID given from receiving packets. 

If the process executing the call is not the 

owner of the PID, the process must be 
pr ivi leged. 



Argument 
PID 

Value Returned 
None 



.MUGTI 



Return the PID associated with <SYSTEM>I NFO. 



Argument 

PID or job number 

Value Returned 

PID of <SYSTEM>INFO 



.MUCPI 



Create a private copy of <SYSTEM>INFO for the 
specified job. The caller must have IPCF 
capability enabled. 



Argument 

PID to be assigned to <SYSTEM>INFO 

PID or number of job creating private copy 
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Function Meaning 



•MUDES Delete the PID given. The process executing the 

call must own the PID being deleted. 

Argument 

PID to be deleted 

Value Returned 
None 

•MUCRE Create a PID for the process or job given. If 

the job number given is not that of the process 
executing the call, the process must be 
privileged. The flag bits that can be specified 
are I P%JWP and I P%N0A (refer to Table 7-1 for 
thei r descr iptions) . 

Argument 

flag bits in the left half, and process 
handle or job number in the right half 

Value Returned 

PID that was created 

.MUSSQ Set send and receive quotas for the specified 

PID. The caller must have IPCF capability 
enabled. The new send quota is given in bits 
18-26, and the new receive quota is given in 
bits 27-35 • The receive quota applies to the 
specified PID, but the send quota applies to the 
job to which that PID belongs. 

Argumemts 

PID 

new quotas 

.MUFOJ Return the number of the job associated with the 

PID given. 

Argument 
PID 

Value Returned 

Job number associated with PID given 
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Function Meaning 



.MUFJP Return all PIDs associated with the job given. 

Argument 

job number or PID belonging to the job 

Values Returned 

Two-word entries for each PID belonging to 
the job. The first word of the entry is the 
PID, and the second word has bits I P%JWP and 
I P%N0A set if appropriate {refer to Table 
7-1 for the descriptions of these bits). 
The list of entries returned is terminated 
by a zero word. 

.MUFSQ Return the send quota and the receive quota for 

the PID given. 

Argument 
PID 

Values Returned 

Send quota in bits 18-26 and receive quota 
in bits 27-35. 

•MUFFP Return all PIDs associated with the process of 

the PID given. 

Argument 
PID 

Values Returned 

Two-word entries for each PID belonging to 
the process. The first word of the entry is 
the PID, and the second word has bits I P%JWP 
and I P%N0A set if appropriate (refer to 
Table 7~1 for the descriptions of these 
bits). The list of entries returned is 
terminated by a zero word. 

•MUSPQ Set the maximum number of PIDs allowed for the 

specified job. The caller must have IPCF 
capabi 1 i ty enabled. 

Argument 

job number or PID 
PID quota 
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Table 7~7: MUTIL% Functions (Cont.) 



Function 



Meaning 



.MUPIC 



Place the specified PID on a software interrupt 
channel. An interrupt is then generated when: 

1. The MUPIC function is issued while the PID 
has one or more messages in its receive 
queue. 



2. The PID's receive queue changes its state 
from empty to containing a message. 
Subsequent entries to a queue that is not 
empty do not cause an interrupt. 



If the channel number is given as 
removed from its current channel. 



1 , the PID is 



The calling process and the process that owns 
the specified PID must belong to the same job. 



Arguments 
PID 
channel 



number 



.MUDFI 



Set the PID of <SYSTEM>INFO. An error is given 
if <SYSTEM>INFO already has a PID. The caller 
must have IPCF capability enabled. 

Arguments 

PID of <SYSTEM>INFO 



.MURSP 



Return a PID from the system PID table. The PID 
is returned in word 2 of the argument block. 
The system PID table currently has the following 
entr ies: 






.SPIPC 


Reserved for Digital 


1 


.SPINF 


PID of <SYSTEM>INFO 


2 


.SPQSR 


PID of QUASAR 


3 


.SPMDA 


PID of QSRMDA 


k 


•SPOPR 


PID of ORION 



Argument 

index into system PID table 
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Table 7~7: MUTIL% Functions (Cont.) 



Function 



.MUMPS 



Meani ng 



Return the maximum packet size for 
given. 

Argument 
PID 



the PID 



.MUSKP 



Value Returned 

Maximum packet size for PID 



Set PID to receive 
a control ler tas 
subordinate tasks 
is performed, if 
deleted (via RES 
function) , the mon 
to the control 1 i ng 
subordinate PID h 
contains .IPCKP in 
word 1 . 



deleted PID messages. Allows 
k to be notified if one of its 
crashes. After this function 
the subordinate PID is ever 
ET or the .MUDES MUTIL 
i tor will send an I PCF message 

PID notifying it that the 
as been deleted. This message 

word and the deleted PID in 



Argument 

Source (subordinate) PID 

Object (controller) PID 

.MURKP Return controlling PID for this subordinate PID, 

Argument 

Source (subordinate) PID 

Object (controller) PID (returned) 



On successful completion of the MUTIL% monitor call, the function 
requested is performed, and any value is returned are in the argument 
block. Execution of the user's program continues at the second 
location following the MUTIL% call. 

If execution of the MUTIL% monitor call is not successful, no 
requested function is performed and an error code is returned in AC1. 
Execution of the user's program continues at the location following 
the MUTIL% call . 
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CHAPTER 8 
USING EXTENDED ADDRESSING 



The term "extended addressing" refers to the size of the addresses 
that TOPS-20 uses on the DECSYSTEM-20 Extended KL10 processor. Older 
versions of TOPS-20 (Release k.] and before) used 18-bit addresses; 
newer versions (Release 5 and after) use 30-bit addresses. 

This chapter discusses the two main activities associated with using 
TOPS-20 monitor calls with extended addressing: 

1. Writing new programs for execution in sections of memory 
other than section 

2. Converting existing programs so that they can be executed in 
sections other than section 

This chapter also contains information on hardware instructions and 
macros useful to MACRO programmers who use extended addressing. 

The discussion in this chapter depends heavily on the material in the 
DECsystem-10/DECSYSTEM-20 Processor Reference Manual . Refer to that 
manual for a description of the format of 30-bit addresses, the 
algorithm the processor uses to calculate effective addresses, and the 
way that individual machine instructions work. 



8.1 OVERVIEW 

The TOPS-20 extended address space contains 32 (decimal) sections. 
Each section contains 512 pages of 512 words each (25bK words). An 
18-bit address, called a local address, can reference any word in a 
given section. A 30-bit, or global, address can reference any word in 
any section of memory. 
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In contrast, TOPS-20 \A.l and earlier provided an 1 8-bit, 256K-word 
address space. The Program Counter (PC) register was 18 bits. For 
each instruction executed, the first action taken was the computation 
of an 18-bit effective address. The algorithm for calculating the 
effective address (including indexing and indirecting rules) was the 
same for all instructions. 

Because the TOPS-20 virtual address space is limited to 32 sections, 

and section numbers longer than 5 bits are illegal, legal addresses 

are effectively limited to 23 bits. When addressing data, you can 
view this 32-section address space as one large memory area. 

From the point of view of program execution, however, memory is 
divided into 32 discrete sections. A program can have code in more 
than one section of memory, and it can execute that code (assuming the 
constraints discussed below), but it must change sections explicitly, 
as discussed below. 

Compatibility for existing programs is provided by section 0. A 
program running in section behaves as though it were being executed 
on a system without extended addressing, except for certain 
instructions such as X JRSTF . For more information on the actions of 
specific instructions, see the DECsystem-10/DECSYSTEM-20 Processor 
Reference Manual. 



8.2 ADDRESSING MEMORY AND ACS 



a 



The extended format PC contains a section field and 
word-wi thin-section field. When an instruction is executed, only the 
word field is incremented. Column overflow is never carried from the 
word field to the section field. If the last word of a section is 
executed, and it is not a jump instruction, then the next instruction 
is fetched from word of the same section. Thus a program can only 
change sections explicitly, by means of a PUSHJ, JRST, XJRST or XJRSTF 
instruction, and only an XJRST or an XJRSTF can change control from 
section to another section. 
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| Because a whole word cannot contain a 30-bit address and the program 
| flags, the PC and flags are a two-word entity. The flag bits are in 

the first word, and the figure below represents the second word. 

Figure 8-1 shows the format of the address fields of the PC. 



5 6 17 18 35 

! un- ! section ! word-within- ! 
! used ! number ! section ! 



Figure 8-1: Program Counter Address Fields 

The word (word-wi thi n-section) field consists of 18 bits and thus 
represents a 256K-word address space similar to the single-section 
address space of release k and earlier. The section number field is 
I 12 bits, of which only the right-hand five bits can be nonzero because 
j section numbers greater than 31 are illegal. The leftmost seven bits 
j of the section number field must be zero. This provides room to 
j address 32 separate sections, each of 256K words. 

Each section is further divided into pages of 512 words, just as in 
earlier releases. The paging facilities allow the monitor to 
determine the existence and protection of each section. 

The PC section field determines what section a program is running in. 
If the section field contains zero, the program is running in section 
0. Most extended addressing features are not available to a program 
running in section 0. All quantities (including addresses), when 
calculated from section 0, are considered to be local (18 bits). 

1. A program executing in section cannot address memory in any 
other section. (One-word global byte pointers are an 
exception to this rule. Refer to Chapter 1 of the TOPS-20 
Moni tor Cal Is Reference Manual for more information.) 

2. The program cannot jump from section to another section 
unless it uses a monitor call or the XJRST or XJRSTF 
i nstruct ion. 

I 3« The program runs exactly as it would run on a machine without 
j extended addressing. 

I 

I If the section field contains a number from 1 to 31 (decimal) 

I inclusive, the program is executing in a nonzero section (a section 

I other than section 0). The hardware considers addresses to be 30 

j bits, and the program can use extended addressing features. 
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| A local address is defined as an 18-bit address in the same section as 

| the program counter (PC) of the instruction. Local addresses are 

J relative to the PC section. A global address is a 30-bit address, 

j which therefore supplies its own section number. 

The following paragraphs explain the way effective addresses are 
calculated in nonzero sections. In addition, see the description in 
| the DECsystem-10/DECSYSTEM-20 Processor Reference Manual . 



8.2.1 Instruction Format 

The format of a machine instruction is the same as on an unextended 
machine. The effective address calculation depends on the address 
field (Y, 18 bits), the index field (X, h bits), and the indirect 
field (I, 1 bit). Figure 8-2 shows these fields. 



8 9 12 13 !*♦ 17 18 



35 



i 



i 



OPCODE ! AC ! I ! 



i 



! 



! 



Figure 8-2: Instruction Word Address Fields 



If I and X are 0, the instruction uses neither indexing nor 
indirection, so the effective address is Y (18 bits). The section 
number, since it is not specified in the address, is taken from the 
section field of the PC. The PC section field contains the number of 
the section from which the instruction was fetched. Such an 18-bit 
address is called a local address. 

The following is an example of an instruction whose I, X and Y fields 
evaluate to an 1 8-b 1 t effective address. 



MOVEM T.1000 



The effective address 
section from which 



3,^00/ 

is word 1000 of the current section. The 
the instruction is fetched is section 3. so the 



instruction moves the contents of register T into memory word 3»»1000, 
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8.2.2 Indexing 

The first step in the effective address calculation is indexing. If 
the X field is nonzero, indexing is used. The calculation of the 
effective address then depends on the contents of the specified index 
register. Indexing may be local or global as follows: 

• If the left half of the index register contains a negative 
J number or zero, the contents of the right half (bits 18-35) 

j are added to Y (from the instruction word) to yield an 18-bit 

local address. 

This is the way indexing is done on an unextended machine. 
It allows a program to use the usual AOBJN pointer and stack 
pointer formats for tables and stacks that are in the same 
section as the program. Note, however, that if the left half 
of the index register contains a positive number, the results 
are not the same. 

• If the left half of the index register contains a positive 
| number, the contents of bits 6-35 of the register are added 
j to Y to yield a 30-bit global address. 

This means that instructions can reference 30-bit (global) 
addresses by means of an index register. If the Y field is 
0, the instruction refers to the address contained in X. The 
Y field can contain a positive or negative offset of 
magnitude less than 2 A 17- 



8.2.3 Indirection 

If the I field contains 1, the instruction specifies indirection. An 
indirect word is fetched from the address determined by Y and X. Two 
types of indirect word exist, Instruction Format Indirect Word (IFIW) 
and Extended Format Indirect Word (EFIW). They are described in the 
fol lowi ng section. 
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8.2.3.1 Instruction Format Indirect Word (IFIW) - This word contains 
Y, X, and I fields of the same size and in the same position as 
instructions (in bits 13-35) • Bit must be 1, and bit 1 must be 0; 
bits 2-12 are not used. 

| Figure 8-3 shows an instruction format indirect word. 



1 2 



12 13 14 17 18 



35 



! ! ! ! ! 

! 1!0! (not used) ! I ! X 
! ! I ! ! 



Figure 8-3: Instruction Format Indirect Word 



The effective address calculation continues with the quantities in 
this word just as for the original instruction. Indexing can be 
specified and can be local or global depending on the left half of the 
index. Further indirection can also be specified. 



Note that the default section for any local addresses produced from 
this indirect word is the section from which the word itself was 
fetched. This means that the default section can change during the 
course of an effective address calculation that uses indirection. The 
default section is always the section from which the last address word 
was fetched. 



8.2.3.2 Extended Format Indirect Word (EFIW) - This 
contains Y, X, and I fields, but in a different format, 
shows an extended format indirect word. 



word also 
Figure 8-4 



1 2 



5 6 

! < 

! 
I 



17 18 



35 

-> ! 



0! I ! 
! ! 



! (section) 



(word) 



Figure 8-4: Extended Format Indirect Word 
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If indexing is specified in this indirect word (bits 2-5 nonzero), the 
contents of the entire index register are added to the 30-bit Y to 
produce a global address. This type of indirect word never produces a 
local address. The type of address calculation used does not depend 
on the contents of the index register specified in the X field. 

Hence either Y or Y (X) can be used as an address or an offset within 
the extended address space, just as is done in the 18-bit address 
space. If further indirection is specified (bit 1 set), the next 
indirect word is fetched from Y as modified by indexing (if any). The 
next indirect word can be in instruction format or extended format, 
and its interpretation does not depend on the format of the previous 
indirect word. 



8.2.3.3 Macros for Indirection - The system file MACSYM.MAC contains 
several convenient macros for constructing indirect words. Macro 
LFIWM generates local (instruction format) indirect words. Both the 
macros EP. and GFIWM may be used to generate global (extended format) 
indirect words. 



8. 2. A AC References 

I A local address in the range 0-17 (octal) references the hardware ACs 
J as memory. This is true in every section of memory. 

A global address in section 1 in the range 1,,0 to 1,,17 (octal) also 
I refers to the hardware ACs. A global address in any other section 
j refers to memory. This means that the following behavior occurs. 

I 1. Addresses in the range 0- 17 reference ACs as expected. The 
i nstruct ion 

MOVE 2,3 

fetches the contents of hardware register 3 regardless of 
what section the instruction executes in. 

2. To make a global reference to an AC, the global address must 
contain a section number of or 1. 

3. Arrays can cross section boundaries. Global addresses 
specifying any section except section 1 always refer to 
memory, never to the hardware ACs. For this reason, 
incrementing the address 6,, 777777, for example, yields 
address 7». 000000, which is a memory location. 

k. The ACs are regarded as local to any section; a local address 
(0-17) references the ACs from any section. Hence, a jump 
instruction which yields a local effective address of 0-17 in 
any section will cause code to be executed from the ACs. 
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8.2.5 Extended Addressing Examples 

These instructions make local references within the current PC 
section: 

3,, ^00/ MOVE T.1000 ; fetches from 3.. 1000 

JRST 2000 ; jumps to 3,, 2000 

The following instructions scan table TABL, which is in the current 
section: 

MOVSI X.-SIZ 
LP: CAMN T,TABL(X) ; TABL in current section 

JRST FOUND 
AOBJN X..LP 



The following instructions scan table TABL, which is in section TSEC, 
by using a global address: 

MOVEI X,0 
LP: CAMN T,@[GFIWM TSEC, TABL (X) ] ; extended format 
JRST FOUND 
CAIGE X.SIZ-1 
AOJA X.LP 

Similarly, the EP. macro can be used for the same purpose: 

MOVEI X,0 
LP: CAMN T,@[EP.<TSEC>B17 ITABL (X) ] 
JRST FOUND 
CAIGE X.SIZ-1 
AOJA X.LP 
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The following examples illustrate various aspects of indexing and 
indirection in effective address calculation: 

VI 00 

6,,1000/MOVE 1,@2000 
6,,2000/LFIWM @i»000 
6,,it000/LFIWM 200(4) 

Effective address = 300 in section 6 



6,, SUB/ MOVE 1,@[LFIWM @ZZZ] 

6,,ZZZ: LFIWM @XXX 
XXX: LFIWM ARRAY (it) 

Effective address = ARRAY+100 in section 6 



6/lit,,ADDRX 

11..R0U/M0VE 1,@[LFIWM (6)] 

H,,ADDRX: LFIWM 100 

Effective address = lit,, 100 



8.2.6 Immediate Instructions 

Each effective address calculation yields a 30-bit address, defaulting 
the section if necessary. Immediate instructions use only the 
low-order 18 bits of this as their operand, however, and set the 
high-order 18 bits to 0. Hence instructions such as M0VEI and CAI 
produce identical results regardless of the section in which they are 
executed. 

Two immediate instructions retain the section field of their effective 
addresses. These are: 

• XMOVE I (opcode it 15) Extended Move Immediate 

• XHLLI (opcode 501) Extended Half Word Left to Left Immediate 
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8.2.6.1 XMOVEI - The XMOVEI instruction loads the 30-bit effective 
address into the AC, and sets bits 0-5 to 0. If no indexing or 
indirection is used, the number of the current section is copied from 
the PC to the AC. This instruction can replace MOVE I when a global 
address is needed. 

The following example shows the use of the XMOVEI instruction in a 
subroutine call. The subroutine is in section XSEC, but the argument 
list is in the same section as the calling program. 

XMOVEI AP.ARGLIST 

PUSHJ P,@[GFIWM XSEC.SUBR] 

The subroutine can reference the arguments with the following 
i nstruction. 

MOVE T,@l (AP) 

To construct the addresses of arguments, the subroutine can use the 
following instruction. 

XMOVEI T,@2(AP) 

The last two instructions assume that register AP contains the 
argument list pointer. If the address the calling program placed in 
AP is an IFIW, the section number in the effective address is that of 
the calling program. If the address the calling program placed in AP 
is an EFIW, the section number in the effective address of the 
argument block is determined by the section number the calling program 
placed in AP. 

The argument list would be found in the caller's section because of 
the global address in AP. The section of the effective address is 
determined by the caller, and is implicitly the same as the caller if 
an IFIW is used as the arglist pointer, or is explicitly given if an 
EFIW is used. 



8.2.6.2 XHLLI - The XHLLI instruction replaces the left half of the 

accumulator with the section number of the PC, and places zero in the 

right half of the AC. This instruction is useful for constructing 
global addresses. 



8.2.7 Other Instructions 

The instructions discussed here are affected by extended addressing, 
but not necessarily in the way that their effective addresses are 
calculated. In addition to the material presented here, see the 
DECsystem-10/DECSYSTEM-20 Processor Reference Manual regarding the 
following instructions: LUUOs, BLT, XBLT, XCT, XJRSTF , XJEN, XPCW, 
SFM. 
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8.2.7.1 Instructions that Affect the PC - These instructions are 
PUSHJ, POPJ, JRST. PUSHJ stores a 30-bit PC address, but stores no 
flags. It sets bits 0-5 of the destination word to 0. 

POPJ restores a 30-bit PC address from the stack, but does not restore 
the flags. It also sets bits 0-5 of the destination word to 0. 

The JSA and JRA instructions can be used only within a section. In 
section the JSP and JSR instructions can store flags,, PC but then 
cannot transfer out of section 0. The JSP and JSR instructions can 
store flags,, PC in nonzero sections and then can transfer into any 
other section (if the address is specified with indexing or 
indi recti on) . 



8.2.7.2 Stack Instructions - PUSHJ, POPJ, PUSH, POP, and ADJSP. 
These instructions use a local or global address for the stack 
according to the contents of the stack pointer. Whether the stack 
address is local or global depends on the same rules as those that 
govern indexing in effective address calculation. (See section 
8.2.2.) It is always best to use the ADJSP instruction when working 
with stacks. This instruction works in any section and will indicate 
when a pushdown overflow error occurs. 

In brief, if the left half of the stack pointer is zero or negative 
(prior to incrementing or decrementing), the pointer references a 
local address and the address in its right half is the address of the 
current item in the stack. The stack pointer is incremented or 
decremented by adding or subtracting one from both sides, 
respectively. 

If the left half of the stack pointer is positive, the entire word is 
taken as a global address. The stack pointer is incremented by adding 
1, and decremented by subtracting 1. 

A stack that contains global addresses can be used the same way a 
local stack is used. The global stack, however, can contain pointers 
to routines in other sections. 

To protect against stack overflow and underflow, make the pages before 
and after the stack inaccessible. This method must be used because a 
global stack has no room for a count in the left half of the pointer. 



8.2.7.3 Byte Instructions - To reference a byte in another section, 
you must use either a one-word, or a two-word, global byte pointer. 
Both global and local byte pointers are legal arguments to monitor 
calls from nonzero sections but there are some restrictions on the use 
of one-word global byte pointers from section 0. See Section 8.3 for 
further information. 
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Chapter 1 of the TOPS-20 Monitor Cal Is Reference Manual describes 
one-word global byte pointers. The DECsystem-10/DECSYSTEM-20 
Processor Reference Manual describes two-word global byte pointers. 



8.3 USING MONITOR CALLS 

If a program runs in a single section, even though that section is not 

section 0, most monitor calls execute exactly the way they do in 

section 0. This is because when no section number is specified, the 
current section is the default. 

The GTFDB% call, for example, requires that AC3 contain the address of 
the block in which to store the data it obtains from the file data 
block. This address can be an 18-bit address regardless of what 
section the monitor call is made from. When the monitor sees that the 
address is local, it obtains the section number from the PC of the 
process that makes the call. 

The same is true of calls that accept page numbers. If a 9"bit page 
number is passed as an argument, the monitor obtains the section 
number from the PC of the process that made the call. Monitor calls 
arguments are discussed in Chapter 1 of the TOPS-20 Moni tor Cal Is 
Reference Manual . 

It is sometimes desirable to specify addresses in section when 
executing a JSYS from a nonzero section. The bit PM%EPN for PMAP%, 
and FH%EPN for JSYSs that accept fork handles, prevent the current 
section (the section in which a program is running) from being the 
target section for the monitor call's arguments. 

Another restriction on arguments passed to monitor calls executed in 
sections other than section concerns universal device designators, 
which have the format 5xxxxx, .xxxxxx or 6xxxxx, .xxxxxx (.DVDES) . 
Universal device designators are not legal except in section 0. This 
is because of the existence of one-word global byte pointers, which 
can have the same format. 

Thus monitor calls that accept either a device designator or a byte 
pointer when called from section do not accept universal device 
designators in any other section. Other device designators, such as 
.TTDES (0, .Axxxxx) , can be used in any section. Conversely, these 
monitor calls that can accept either universal device designators or 
byte pointers do not accept one-word global byte pointers in section 
0. 

The calls SIR% and RIR% should not be used in sections other than 
section 0. These calls work in other sections only if all the code 
associated with these calls exists in the same section as the code 
that makes the cal 1 . 
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For example, if an SIR% call is executed in section k, it executes 

correctly if and only if the code that generates the interrupts, the 

i nterrupt-process ing routines, and all associated tables are also 

located in section k. Thus, in programs intended to run in a section 

other than section 0, the XSIR% and XR I R% calls, described in Chapter 

| 4, should be used in place of S I R% and RIR%. In general, it is 

j recommended that the extended form of monitor calls be used since this 

j form works in any section, including section 0. 



8.3- 1 Mapping Memory 

The PMAP% monitor call accepts an 1 8-bit page number, half of which is 
a section number. Thus PMAP% can be used to map a page from one 

| section to another. If the destination section does not exist, that 

j section will be created. 

The SMAP% monitor call maps one or more sections of memory. It works 
| like the PMAP call, but maps sections instead of pages. If the 
destination section does not exist, SMAP% creates the section. 

Access to the sections in a process map is determined by the same 
algorithm that determines access to a page within a given section. If 
a process section and a page in that section have different accesses, 
the access privileges are ANDed together. The process requesting 
access to the page gains access only if it has access rights at least 
equal to the ANDed protections. 

For example, if a process has read access to a section and maps a page 

into that section for which the process has read and write access, the 

page is mapped, but the process gets only read access to the mapped 
page. 

The following sections describe the SMAP% functions. 



8.3-1 • 1 Mapping File Sections to a Process - This function maps one 
or more sections of a file to a process. All pages that exist in the 
source sections are mapped to the destination sections. Access to the 
mapped pages is determined by ANDing the access allowed to the file 
and the access specified in the SMAP% call. 

Although files do not actually have section boundaries, this monitor 
call views them as having sections that consist of 512 contiguous 
pages. Each file section starts with a page number that is an integer 
mul ti pie of 512. 
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This call cannot map a process memory section to a file. To map a 
process section to a file, use the PMAP% moni tor cal 1 to map the 
section page-by-page. 

This function of the SMAP% call requires three words of arguments, as 
fol lows: 

AC1: source identifier: JFN,,file section number 

AC2: destination identifier: fork handle, .process section number 

AC3: flags,, count 

The flags determine access to the destination section, and the count 
is the number of contiguous sections to be mapped. The count must be 
between and 37 (octal). The flags are as follows. 

B2 (SM%RD) Allow read access 

B3 (SM%WR) Allow write access 

Blt(SM%EX) Allow execute access 

B18-35 The number of sections to map. This 
number must be between 1 and 37 (octal) . 



8.3.1.2 Mapping Process Sections to a Process - The SMAP% monitor 
call also maps sections from one process to another process. In 
addition, you can map one section of a process to another section of 
the same process. The SMAP% call maps all pages that exist in the 
source section to corresponding pages in the destination section. 

If you map a source section into a destination section with SM%IND 
set, SMAP% creates the destination section using an indirect pointer. 
This means that the destination section will contain all pages that 
exist in the source section, and the contents of the destination pages 
will be identical to the contents of the source pages. 

Furthermore, after SMAP% has mapped the destination section, changes 
that occur in the source section map cause the same changes to be made 
in the destination section map. This ensures that both the source 
section and the destination section contain the same data. 

If SM%IND is not set, SMAP% creates the new section using a shared 
pointer. After SMAP% maps the destination section, changes that occur 
in the source section's map do not cause any change in the destination 
section's map. Thus after a short time the source and destination 
sections might contain different data. 
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If you request a shared pointer (SM%IND not set) to the destination 
section, what happens depends on the contents of the source section 
when the SMAP% call executes. The outcome is one of the following. 

1. If the source section does not exist, the SMAP% call creates 
the section. 

2. If the source is a private section, a mapping to the private 
section is established, and the destination process is 
co-owner of the private section. 

3. If the source section contains a file section, the source 
section is mapped to the destination section. 

k. If the source section map is made by means of an indirect 
section pointer, SMAP% follows that pointer until the source 
section is found to be nonexistent, a private section, or a 
section of a file. 

This SMAP% function requires three words of arguments in AC1 through 
AC3. 

AClt Source identifier: fork handle, .section number 

AC2: Destination identifier: fork handle, .section number 

AC3: access flags,, the number of contiguous sections to map. 

The number of sections mapped, the number in the right 
half of AC3, must be between 1 and 37. 

The flags determine access to the destination section. 
The flags are as follows: 

B2(SM%RD) Allow read access 

B3(SM%WR) A 1 low write access 

B4 (SM%EX) Allow execute access 

B6(SM%IND) Map the destination section using an indirect 
section pointer. Once the destination section map 
is created, the indirect section pointer causes 
the destination section map to change in exactly 
the same way that the source section map changes. 

B 1 8-35 Count of the number of contiguous sections to be 
mapped. 
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8.3.1-3 Creating Sections - Before you can use a nonzero section of 
memory, you must create it. If your program references a nonzero 
section of memory that does not exist (that is not mapped), the 
instruction that makes the reference fails. 

This SMAP% function requires three words of arguments in AC1 through 
AC3, as fol lows: 

AC1: 

AC2: destination identifier: fork handle, .sect ion number 

AC3: flags,, count 

The flags determine access to the destination section, and the count 
is the number of contiguous private sections to be created. This 
count must be between 1 and 37- 

The flags in the left half of AC3 are as follows: 

B2(SM%RD) Allow read access 

B3(SM%WR) Allow write access 

B4 (SM%EX) Allow execute access 

B6(SM%IND) Create the section using an indirect pointer 

B18-35 The number of sections to create. This number 
must be between 1 and 37. All created sections 
are contiguous. 



8.3.1.4 Unmapping a Process Section - You can use the SMAP% monitor 
call to unmap one or more sections of memory in a process. The 
contents of the section are lost. 

If the section contains pages mapped from a file, this function does 
not cause the unmapped sections to be written back to the file from 
which they were mapped. Such pages must be mapped to the file by 
means of the PMAP% call. 
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This function requires three words of arguments in AC1 through AC3, as 
foil ows . 

AC1: -1 

AC2: Destination identifier: fork handle, .sect ion number 

AC3: 0,, count 

The count is the number of contiguous sections to be 
unmapped. This number must be between 1 and 37. 



8.3.2 Starting A Process In Any Secti 



on 



You can use most of the calls described in Chapter 5 to control 
programs that run in a nonzero section. The SF0RK% monitor call is an 
exception, and will not start a program in a nonzero section. 

The XSFRK% monitor call starts a process in any section of memory. If 
the process is frozen (by means of the FF0RK% call), XSFRK% changes 
the double-word PC, but does not resume execution of the process. To 
resume the execution of any frozen fork, use the RF0RK% call. 

The XSFRK& call requires three words of arguments in AC1 through AC3. 

AC1: flags, .process handle 

Flags: 

SF%CON(1BO) continue a process that has halted. 
If SF%C0N is set, the address in AC3 
is ignored and the process continues 
from where it was halted. 

AC2: PC flags, ,0 

AC3: address to which this call is to set the PC 

The XSFRK% call also starts a process in section 0. To do so, set the 
left half of AC3 to zero and the right half of AC3 to the address in 
section at which you want the process to start. 

Most other calls consider an address with a zero in the left half to 

be a local address. The XSFRK% call, however, uses the contents of 

AC3 to set the PC. A PC with zero in the left half indicates an 
address in section 0. 
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8.3.3 Setting the Entry Vector In Any Secti 



on 



j The SEVEC% monitor call has room in its argument ACs for only a 
J half-word address, so it cannot be used to set a process entry vector 
to an address in a nonzero section. The XSVEC% call, on the other 
hand, uses an AC for the address of the entry vector, and another AC 
for the length of the entry vector, and can specify an entry vector in 
any section of memory. 

The XSVEC% call requires three words of arguments in AC1 through AC3. 

AC1: process handle 

AC2: length of the entry vector, or 

AC3: address of the beginning of the entry vector 

The length of the entry vector specified in AC2 must be less than 1000 
words. If AC2 contains 0, TOPS-20 assumes a default length of two 
words. 



8 . 3 - ^+ Obtaining Information About a Process 

Although the monitor calls described in Chapter 5 work in any section 
of memory, several of them can only return information about the 
section in which they are executed. The following paragraphs describe 
the monitor calls you can use to obtain information about any section 
of memory. 



8.3.4.1 Memory Access Information - Several kinds of information 
about memory are important. Among them are whether a page or section 
exists (is mapped), and, if so, what the access to a page or section 
is. The RSMAP% and XRMAP% calls provide this information. 

The RSMAP% monitor call reads a section map, and provides information 
about the mapping of one section of the address space of a process. 
RSMAP% requires one word of arguments in AC1: a fork handle in the 
left half, and a section number in the right half. It returns the 
access information in AC2. 
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The map information that RSMAP% returns in AC1 can be the following: 

_1 no current mapping present (the section does not 

exist) 







the mapping is a private section 



n »» m where n is a fork handle or a JFN, and m is a 

section number. If n is a fork handle, 
the mapping is an indirect or shared 
mapping to another fork's section. If n 
is a JFN, the mapping is a shared 
mapping to a file section. 

The access information bits returned in AC2 are the following: 

B2 (SM%RD) Read access is allowed 

B3(SM%WR) Write access is allowed 

BA(SM%EX) Execute access is allowed 

B5(PA%PEX) The section exists 

B6(SM%IND) The section was created using an indirect pointer. 

Although the RSMAP% call does not return information on individual 
pages, the data it does return is useful in preventing error returns 
from the XRMAP% monitor call. 
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The XRMAP% call returns access information on a page or group of pages 
in any section of memory. Although the RMAP% call returns access data 
about a page in the current section, and you can use the RSMAP% call 
in any section of memory, you must use the XRMAP% call to obtain 
information about pages in any section other than the current section. 

The XRMAP% call requires two words of arguments in AC1 and AC2. 

| AC1: process handle, ,0 

AC2: address of the argument block 

The argument block addressed by AC2 has the following format: 



Length of the argument block, including this word ! 
number of pages in this group on which to return data 



number of the first page in this group 



I 

! address at which to return the data block 

\ • \ 

\ . \ 

\ • \ 

number of pages in this group on which to return data ! 



number of the first page in this group 



address at which to return the data block 



The number of words in the argument block is three times the number of 
groups of pages for which you want access data, plus one. Each group 
of pages requires three arguments: the number of pages in the group, 
the number of the first page in the group, and the address at which 
the monitor is to return the access data. 

Note that the address to which the monitor returns data should be in a 
section of memory that already exists. If it does not exist, the call 
will fail with an illegal memory reference. 
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The access information returned for each group of pages specified in 
the argument block is the following: 

B2 (RM%RD) read access allowed 

B3 (RM%WR) write access allowed 

Bk (RM%EX) execute access allowed 

B5(RM%PEX) page exists 

B9(RM%CPY) copy-on-wr ite access 

For each page specified in the argument block that does not exist, 
XRMAP% returns a -1. It also returns a zero flag word for each such 
page. The data block to which XRMAP% returns the access information 
should therefore contain twice as many words as the number of groups 
of pages about which you want information. 

If you execute an XRMAP% call to obtain information about a page in a 
nonexistent section, the XRMAP% call fails with an illegal memory 
reference. For this reason it is recommended to execute an RSMAP% 
call to determine that the section exists before you use XRMAP% to 
obtain information about any page within that section. 



8.3.^.2 Entry Vector Information - To obtain the entry vector of a 
process in any section of memory, use the XGVEC% call. This call 
returns the length of the entry vector in AC2 and the address of the 
entry vector in AC3« 

The XGVEC% call requires one word of argument: in AC1, the handle of 
the fork for which you want the entry vector. 



8.3-^*3 Page-Failure Information - A page-fail word, described in the 
DECsystem-10/DECSYSTEM-20 Processor Reference Manual , contains 
information that allows a program to determine the cause of a page 
trap and the address of the instruction that caused the trap. This 
information allows a program to correct the cause of the page-fail 
trap. Once the program has corrected the cause of the page-fail trap, 
the program can continue execution. 

The XGTPW% call obtains the page-fail word from the monitor's data 
base, and returns it to the calling program's address space. The 
XGTRP% call requires two words of arguments in AC1 and AC2. 

AC1: process handle 

AC2: address of the block in which to return data 
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8.3.5 Program Data Vectors 

Program Data Vectors (PDVs) are data structures in a process that are 
known to the monitor by name and location. They contain information 
about the program segments within a process. The PDV is a block of 
data that LINK writes into memory when loading and linking a program. 
The PDV resides in memory as a part of the program, and starts at a 
program data vector address (PDVA) . PDVs are used to allow user 
programs to obtain information about other programs that can be mapped 
into a process. PDVs and PDVAs are manipulated by using the PDV0P% 
monitor call. (Refer to the TOPS-20 Monitor Cal Is Reference Manual 
for a complete description of the PDV0P% monitor call.) The PDV0P% 
monitor call can be used to obtain information about an execute-only 
process. 

Certain words in the PDV (for example, .PVNAM) point to blocks of 
information. These words are in either 1FIW or EFIW format (see 
Sections 8.2.3- 1 and 8.2.3-2) except that they cannot use indexing, 
and any indirect chain pointed to by the word cannot go through an 
accumulator. This allows a program to find the address of a block 
pointed to by a PDV word by simply using an XMOVE I instruction. For 
example, 

XMOVE I AC1,@. PVNAM (AC2) 

puts into AC1 the global address of the name of the PDV whose PDVA is 
in AC2. 



8.3.5.I Manipulating PDV Addresses - For the process specified in 
word .POPHD of the argument block, the .POGET function of the PDV0P% 
monitor call returns all PDVAs within the range of addresses specified 
in words .POADR and .POADE of the argument block. (See the 
description of the PDV0P% monitor call in the TOPS-20 Monitor Cal Is 
Reference Manual for the format of the argument block.) The address 
range supplied by words .POADR and .POADE determines which PDVAs are 
affected by any given call. 

The .POADD function of the PDV0P% monitor call adds the PDVAs 
specified in the data block to the system's data base for the 
specified process. The PDVAs must be in ascending order within the 
data block. 

The .POREM function of the PDV0P% monitor call removes a set of PDVAs 
from the system's data base for the specified process. Those removed 
are the ones within the range specified by words .POADR and .POADE of 
the argument block. 
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8,3.5.2 PDV Names - The .PONAM function of the PDV0P% monitor call 
returns the ASCIZ name of a PDV in memory. Word .POADR of the 
argument block must contain a valid PDVA for the specified process. 
The name returned is the one to which word . PVNAM of the PDV points. 
The string returned by .PONAM is placed into the data block. 

For the specified process, the .POLOC function returns in the data 
block all the PDVAs of PDVs with the specified name. The byte pointer 
in AC3 points to the PDV name. Function .POLOC is affected by 
. POADR/. POADE words. 

The following rules apply to the assignment of PDV names. If these 
rules are followed, it is quite unlikely that two packages that want 
to run in the same process will discover a conflict in PDV names. 

1. PDV names assigned by DIGITAL will contain the character "%" 
at the end (or elsewhere). No PDV names assigned by users 
should contain the "%" character. 

2. All PDV names containing the character "." are reserved to 
DIGITAL for future use. 

3. The character "$" is reserved for a special use: PDV names 
of the form str ingl$str ing2 are reserved for the special 
class of use named by stringl. Rules 1 and 2 still apply in 
this case. 

As a general principle, avoid using PDV names that are insufficiently 
specific; use of such names invites conflicts with other packages. 



8.3.5.3 Version Number - The .POVER function of the PDV0P% monitor 
call returns in the data block the version of a program in memory. 
Word .POADR must contain a valid PDVA for the specified process. The 
version returned is the one that word .PVVER of the PDV contains. 

For more information on program data vectors, including explanations 
of the static memory map (pointed to by word .PVMEM) and the symbol 
table vector (pointed to by word .PVSYM) , refer to the TOPS-20 LINK 
Reference Manual. 



8. it MODIFYING EXISTING PROGRAMS 

Existing programs can be modified to run in any section of memory, 
including both section and all other sections. The sections that 
follow discuss the changes that must be made to an existing program so 
that it runs in a single nonzero section. 
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8.4.1 Data Structures 

Stacks, tables, and other data structures used in the past have often 
contained words with an address in the right half and a count in the 
left half. The count could be positive or negative because all 
programs ran only in section 0, and when the contents of a word were 
evaluated for Effective Address calculation or address use in section 
0, only the right half was considered. 

In all other sections, the entire word is considered to be an address. 
If the left half of the word is negative, the left half is ignored 
when the address is evaluated, and the address is local. Thus for a 
word to contain an address in the right half and a count in the left 
half, the count must be negative. 



8.1*. 1.1 Index Words - Be sure the left halves of index words contain 
a nonpositive quantity. To use the left half of an index register to 
hold a count, the count must be negative. If the left half is unused, 
it must be zero so that the effective address is a local address. If 
the left half contains a positive number, the indexed address will be 
global . 



8.4.1.2 Indirect Words - To be sure that an indirect word in a 
nonzero section is evaluated as a local address, always set bit of 
the indirect word. Argument lists that produce local addresses in 
section 0, for example, will produce local addresses in any section if 
bit is set. 



8.4.1.3 Stack Pointers - As mentioned above, the left halves of stack 
pointers must contain zero or a negative number to produce local 
addresses. A negative number in the left half is considered to be a 
count. A positive number in the left half is considered to be a 
section number. 



8.5 WRITING MULTISECTION PROGRAMS 

Multisection programs, programs that use more than one section of 
memory, are similar to single-section programs that run in nonzero 
sections. They allow you to place tables needed for processing 
interrupts in any section of memory (See Chapter 4), to use very large 
arrays, and to write modules of code that can be dynamically mapped 
into a section of memory and executed. 
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In a single-section program, local addresses and byte pointers are 
sufficient to specify any word or byte in the program's address space. 
In a multisection program, local addresses and byte pointers cannot 
specify any word or byte in the program's address space. Most monitor 
calls use only one AC per argument, so passing two-word global byte 
pointers is not possible. Thus, it is necessary to: 

• keep monitor call arguments in the same section of memory as 
the code making the call, or 

• use global arguments, or 

• use the global form of the monitor call. 

In many multisection programs it is not necessary to keep all the 
arguments required by a call in the same section as the code that 
makes the call. Global arguments are required, and they take several 
forms. Chapter 1 of the TOPS-20 Monitor Cal Is Reference Manual gives 
details on the use of these arguments. 

The following program computes a file checksum by XORing the words in 
all file pages. The program is loaded into section and maps itself 
into section 1. It then jumps into section 1 to access the file data 
loaded into section 15. 

TITLE CHKSUM - COMPUTE A FILE CHECKSUM 

SEARCH MONSYM S STANDARD UNIVERSAL FILES 

SEARCH MACSYM 

.REQUIRE SYSJMACREL JGET JSERR SUPPORT ROUTINES 

STDAC, } DEFINE STANDARD ACS 

> PROGRAM CONSTANTS 

PDLSIZ—100 i SIZE OF STACK 

C0I)8EC-=1 i SECTION TO MAP CODE INTO 

DATSEO=:i.!5 J SECTION TO MAP FILE DATA INTO 

DATPAG=:I.OO 5 PAGE WITHIN DATS EC FOR FILE DATA 

pags:i:Z"-==:i.ooo ssra;: of a page 

CHKSUM J RESET% PRESET THE WORLD 

MOVE P , C 1 W D P Ii I... S 1 7. , P D I... 1 

MOVE T:l. , C.FHSLF, »0:i 5MAP THIS FORKS SECTION 

MOVE T2i[:.FHSLF,i.C0DSEC::i J TO EXTENDED CODE SECTION 

M V X T 3 , S M Z R D ! S M 7„ W R ! S M X E X ! S M 7. 1 N D + 1 5 1 N D I R E C T P 1 N T E R R D , W R , E X 1 S E C T 1 N 

SMAr'% 
E J S H I... T y U N E X P E C T E D F A T A L E R R R 

GETFILS SETZM FII..JFN 5SAY NO FILE SEEN 

TMSG < 
ENTER FILE SPEC TO CHECKSUM: > 5 PROMPT USER FOR FILE 

MOVX T 1 , G J%SHT ! G JZOL.D ! G JZFNS 5 OLD F I LE 

MOVE T2,i:.PRIIN, , .PR I OIL! J READ FILE SPEC FROM TERMINAL 

GTJFN% 5GET FILE SPEC 

ERJMPR BADFIL 5 CANNOT GET FILE TELL USER 

MOVEM TlvFIl I FN 5 SAVE FILE J FN 

MOVX T',; J yFLD(''n36»0FZBSZ) ! OF%RD f RE QUEST READ ACCESS AND 36 BIT BYTES 

OPENFZ 5 OPEN THE FILE 

ERJMPR BADFIL i CANNOT OPEN FILE TELL USER 

XJRST LCODSECi. vDOCHKS3 JENTER EXTENDED SECTION AND DO CHECKSUM 
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badfil; jserr sprint error message 

SKIPE T:l. tFILJFN PIS THERE A J FN 

Rl IFNZ S YES, RELEASE IT 

E JSERR J PRINT ERROR IF' ANY 

JRST GETFIL PAND TRY TO GET FILE AGAIN 

? THE FOLLOWING CODE RUNS IN A NONZERO SECTION AND DOES A CHECKSUM OF THE FILE 
P STORED IN FII...JFN 

DOCHKS: SETZB CU»02 PQi. HOLDS THE CHECKSUM. INITIALLY ZERO 

PQ2 IS THE CURRENT FILE PAGE NUMBER 

CHKLOP! MOVE TlrQ2 PGET FILE PAGE NUMBER 

HRL TltFILJFN SAND FILE JFN 

FFUFPZ SFIND FIRST USED PAGE 

ERJMPR NOPAGE P CAN'T GO ANALYZE ERROR 

HRRZ 02, Tl P REMEMBER CURRENT PAGE NUMBER 

AOS Q2 J USE NEXT HIGHER PAGE NEXT TIME THROUGH LOOP 
MOVE T2>C<DATSEC>B26+DATPAG:i PTO DATA PAGE IN DATA SECTION 

HRLI T2».FHSLF POP THIS FORK 

MOVX T3fPM%RD J READ ACCESS 

PMAPZ PMAP THE FILE PAGE 

EJSHLT 5 UNEXPECTED FATAL ERROR 

HRLI T1»DATSEC »T1 IS INDEX INTO DATA PAGE, SETUP SECTION 

HRRI T1»DATPAG*PAGSIZ PAND PAGE ADDRESS 

MOVEI T2»PAGSIZ PT2 COUNTS THE WORDS IN A PAGE 

P THE FOLLOWING LOOP HOES THE CHECKSUM FOR A PAGE 

xorlop: XOR Qi><TI) ? checksum this word 

AOS Tl 5 STEP TO NEXT WORD 

SOJG T2r XORLOP J DO THE WHOLE PAGE 

SETO Tlr PUNMAP THE FILE PAGE 

MOVE T2»[:<DATSEC>B26+DATPAG:.l 5 TO DATA PAGE IN DATA SECTION 

HRLI T2..FHSLF POP THIS FORK 

MOVX T3»PMZRD 

PMAP% 

EJSHLT 5 UNEXPECTED FATAL ERROR 

JRST CHKLOP J LOOP FOR MORE PAGES 

P HERE WHEN FFUFPZ FAILS 

NOPAGEJ CAIE T1»FFUFX3 PNO USED PAGE FOUND? 

JSHLT J NO. UNEXPECTED FATAL ERROR 

P PRINT THE CHECKSUM AND QUIT 

TMSG < 
THE FILE CHECKSUM IS: > 

MOVX T1».PRI0U PPRINT IT ON THE TERMINAL 

MOVE T2>G1 PGET THE CHECKSUM 
MOVX T3»N0ZMAG!FLD("DS»N0ZRDX) ^UNSIGNED OCTAL NUMBER 
NOUTZ 

EJSHLT P UNEXPECTED FATAL ERROR 

MOVE TIfFILJFN PGET FILE AGAIN 

CLOSFZ P CLOSE IT 

EJSHLT P UNEXPECTED FATAL ERROR 

HALTFZ PSTOP PROGRAM 

XJRST CCHKSUM3 SJLJMP BACK TO SECTION AND START OVER 

J IF USER CONTINUES 

t STORAGE 

pdlj block pdlsiz ? stack 

filjfn: block i pfile jfn 

end chksum 
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MSEND*, 5-4, 7-7. 7-8, 7-14 

MUTIL*. 5-4, 7-18 

NIN%, 2-4, 2-5, 2-14, 2-16 

NOUT*, 2-6, 2-16 

OPENF*. 3-2, 3-18 

PBIN*, 2-9, 2-16 

PBOUT*, 2-9. 2-16 

PDVOP*, 5-H. 8-22 

PMAP*. 3-27. 3-28, 3-30, 3-31, 
5-H, 5-16, 5-22, 8-13, 
8-16 

PSOUT*, 2-3, 2-16 

RDTTY*, 2-5, 2-10, 2-14, 2-l6 
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RESET*, 2-9, 5-23, 7-6 

RFSTS*, 5-4, 5-18 

RFSTS* long form, 5"l8, 5"20 

RFSTS* short form, 5~l8 

RIN*, 3-26 

RIR*, 4-17, 8-12 

ROUT*, 3-26 

RSMAP*, 8-18 

SAVE*, 5-H 

SEVEC*, 8-18 

SFORK*, 5-4, 5-16 

SFRKV*, 5-17 

SIN*, 3-24, 3-25 

SIR*, 4-7, 4-12, 5-4, 8-12 

SKPIR*. 4-17 

SNAP*, 3-31. 8-13 

SOUT*, 3-24, 3-25 

SPJFN*, 2-3 

SSAVE*, 5-H 

STIW*. 4-16 

WFORK*, 5-4, 5-17, 5-18 

XGTPW*. 8-21 

XGVEC*, 8-21 

XRIR*. 4-18, 8-13 

XRMAP*, 8-20 

XSFRK*, 5-17, 8-17 

XSIR%, 4-7, 4-12, 4-20, 8-13 

XSVEC*. 8-18 
JUMP instruction symbols, 1-4 

ERCAL, 1-4, 5-16 

ERCALR, 1-4 

ERCALS, 1-4, 1-6 

ERJMP, 1-4, 5-16 

ERJMPR, 1-4, 2-14 

ERJMPS, 1-4 
JUMP instructions, 1-4 

KFORK* JSYS, 5-4, 5"23 



Level number 

resource, 6-5 
LEVTAB, 4-9 
LFIWM macro, 8-7 
LINK, 8-22 
Literals, 2-2 
Local 

byte poi nter , 8- 1 1 
Local address, 8-4, 8-5, 8-7 
Local byte pointer, 8-11 
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Lock 

resource, 6-2 
Long form GTJFN%, 3-1^ 
LUUO instructions, 8-10 

MACSYM, 1-2 
MACSYM macros, 1-2 

EJSERR, 1-5 

EJSHLT, 1-5 

EP., 8-8 

indirection, 8-7 
EP., 8-7 
GFIWM, 8-7 
LFIWM, 8-7 

TMSG, 2-4 
Mapping, 8-13 

file page, 3"28 

file section, 3 - 3 1 

file sections to a process, 
8-13 

memory, 8-13 

page, 3"27» 5-15 

process page, 3 - 30 

process section, 8-14 

sections, 8-13 
Memory, 8-2 
Memory sharing, 5"5 
Messages 

receiving process, 7 _ 7 

sending process, 7 - 7 
Moni tor cal 1 s, 1-2 

arguments, 1-2, 1-3 

calling sequence, 1-3 

error returns, 1-4 

for processes, 5 - 8 

I/O, 2-2 

operation code, 1-2 
MONSYM, 1-2, 2-3 
MRECV% JSYS, 5-4. 7-7, 7-10 

arguments, 7"10 

execution, 7 — 1 3 

flagbits, 7-12 

flags returned, 7*13 
MSEND% JSYS, 5-4, 7-7, 7-8, 7"l4 

arguments, 7-8 

execution, 7~10 

flag bi ts, 7"9 
Multiple processes, 5~2 
Multisection programs, 8-24 
MUTIL% JSYS, 5-4, 7-18 

arguments, 7"l8 
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execution, 7 _ 24 
functions, 7 _ 1 9 

NIN% JSYS, 2-4, 2-5, 2-14, 2-16 

example, 2-8 
N0UT% JSYS, 2-6, 2-16 

example, 2-8 

format options, 2-7 
Number 

reading a, 2-4 

writing a, 2-6 

One-word global byte pointer, 2-2, 

8-11, 8-12 
OPENF* JSYS, 3-2, 3-18, 3-30 

access bits, 3~ 1 9 

arguments, 3 - l8 

examples, 3~ 2 1 
Opening a file, 3 _ 17 
Operation code 

moni tor cal 1 s, 1-2 
Output 

termi nal , 2-1 
Output designator 

primary, 2-3 
Ownership, 6-2, 6-18 

exclusive, 6-2, 6- 1 8 

shared, 6-2, 6- 1 8 

Packet, 7-1, 7-2 

receiving a, 7-10 

sending a, 7 _ 8 
Packet data block, 7-2, 7~7. 7-15 

address, 7-6 

length, 7 - 6 
Packet descriptor block, J-2, 
7-15 

flags, 7-3 
Packet format 

IPCF, 7-2 
Page, 3-1 
Page access, 5 - 5 
Page mappi ng, 5-15 

file, 3-27 
Page sharing, 5 - 5 
Page-failure information, 8-21 
Panic channel, 4-5, 4-11, 4-12 
Parallel inferior processes, 5 _ 10 
PBIN% JSYS, 2-9, 2-16 
PBOUT* JSYS, 2-9, 2-16 
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PC, 5-1, 8-1, 8-2, 8-11 

address, 8-1 1 

address fields, 8-2 
PDV, 8-22 

names, 8-23 
rules, 8-23 
PDVA, 8-22 

manipulating, 8-22 
PDVOP% JSYS, 5-H. 8-22 

functions, 8-22 
PID, 7-1, 7-6, 7-13 
PM%EPN, 8-12 

PMAP* JSYS, 3-27, 3-30, 3-31, 
5-H. 5-16, 5-22, 8-13, 8-16 

access bits, 3 _ 28 

arguments, 3-28, 3-30, 5~l6, 
8-16 
POINT pseudo-op, 2-1 
Poi nter 

file, 3~22 
Pooled resources, 6-12 
POP instruction, 8-11 
POPJ instruction, 8-11 
.PR I IN symbol, 2-3, 2-10, 2-16, 

3-22 
Primary input designator (.PRI IN) , 

2-3, 3-22 
Primary output designator 

(.PRIOU) , 2-3, 3-22 
Printing a string, 2-3 
Priority level 

interrupt, 4-12 

software interrupt, 4-4 
Priority level table (LEVTAB) , 

4-9 
.PRIOU symbol, 2-3, 2-10, 2-16, 

3-22 
Process, 1-6, 1-7 

address space, 1-6, 5"11 

capabi 1 i t i es , 5"! 1 

communication, 1-6, 5"3» 5"22 

control , 1-7, 5-4 

deleting inferior, 5"23 

examples, 5"24 

execute-only, 8-22 

handle, 5-5, 5-6, 5-10 

identifiers, 5 - 5 

inferior, l-7> 5-2 

information about, 8— 1 8 

JSYSs for, 5-8 

multiple, 5~2 
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parallel, 5 - 2 

starting in any section, 8-17 

starting inferior, 5"l6 

status word, 5- 1 9 

structure, 1-6, 5 - l 

superior, 1-7, 5 - 2 

terminating inferior, 5 _ 17 

use of resources, 6-5 
Process communication, 1-6, 5~3» 
5-5. 5-22 

sharing pages, 5-22 

software interrupt, 5 -i t» 5~22 
Process control , 5~4 
Process handle, 5"5» 5 _ 6 
Process ID (PID) , 7-1, 7-6, 7~ 13 
Process identifiers, 5"5 
Process initialization, 2-9 
Process mapping, 3~30 
Process messages 

receiving, 7 - 7 

sending, 7"7 
Process relationships, 5~2 
Process section, 3 — 3 1 

unmapping, 8-1 6 
Process status word, 5 - 19 
Process structure, 1-6, 5 - l 
Process unmapping, 3"31 
Program counter, 8-2 

address fields, 8-2 
Program counter (PC), 5"1, 8-1, 
8-11 

address, 8-11 
Program data vector (PDV) , 8-22 

address (PDVA) , 8-22 

manipulating PDVAs, 8-22 

names, 8-23 
rules, 8-23 

program version number, 8-23 
Programs 

multisection, 8-24 
Protection 

resource, 6-4 
Pseudo-ops 

ASCIZ, 1-6 

POINT, 2-1 
PS0UT% JSYS, 2-3, 2-16 

example, 2-8 
PUSH instruction, 8-11 
PUSHJ instruction, 8-2, 8-11 
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Queue, 6-2 
Quota, 7-1 

receive, 7"! 

send, 7~1 

RDTTY% JSYS, 2-5, 2-10, 2-14, 
2-16 

arguments, 2-10 

control bi ts, 2-11 

editing functions, 2-10 

example, 2-14 
Reading a byte, 2-9 
Reading a number, 2-4 
Reading a string, 2-10 
Reading from a f i le 

summary, 3"44 
Receive quota, 7~1 
Receiving a packet, 7*10 
Referencing a file, 3~3 
Releasing a resource, 6-13 
RESET% JSYS, 2-9, 5~23, 7"6 

example, 2-8 
Resource, 6-2 

level number, 6-5 

obtaining information about, 
6-16 

ownership, 6-2, 6-l8 

pooled, 6-12 

protection, 6-4 

releasing a, 6-13 

requesting use of, 6-6 

sharing, 6-1, 6-l8 

use by process, 6-5 
Resource lock, 6-2 
Resource name, 6-4 
Resource ownership, 6-2 
RFSTS% JSYS, 5-4, 5"l8 

long form, 5-l8, 5-20 

status-return block, 5"20 

process status word, 5-19 

short form, 5~l8 
RIN% JSYS, 3-26 
RIR% JSYS, 4-17, 8-12 

example, 4-17 
R0UT% JSYS, 3-26 
RSMAP% JSYS, 8-18 

information returned, 8-19 

SAVE% JSYS, 5-H 
Section 

changing, 8-2 
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creating, 8— 1 6 

nonzero, 8-16, 8-17 

zero, 8-3, 8-12 
Section handle, 8-19 
Section mapping, 8-13 

file, 3-31 

file to process, 8-13 

process, 8-14 
Sections, 8-2 
Send quota, 7"! 
Sending a packet, 7~8 
SEVEC% JSYS, 8-18 
SFM instruction, 8-10 
SF0RK% JSYS, 5-4, 5-l6 

arguments, 5 - l6 
SFRKV% JSYS, 5-17 
Sharer groups, 6-18 

use of, 6-18 
Sharing files, 3"2, 6-1 
Sharing pages, 5 _ 22 
Sharing resources, 6-1, 6-18 
Short form GTJFN%, 3"5 

examples, 3~12 
SIN% JSYS, 3-24, 3-25 

arguments, 3"24 
SIR% JSYS, 4-7, 4-12, 5-4, 8-12 

arguments, 4-7 
SKPIR% JSYS, 4-17 
SMAP% JSYS, 3-31, 8-13 

arguments, 3-32, 8-14, 8-15, 
8-16 

flag bits, 3-32 
Software interrupt, 1-6, 4-11, 
5-22 

channel assignments, 4-5 

channels and priorities, 4-4, 
4-6 

di sabl ing, 4-18 

dismissing, 4-12 

example, 4-21 

panic channel, 4-5, 4-11, 4-12 

pr ior i ty level , 4-12 

priority levels, 4-4 

process communication, 5 - 4 

process i ng, 4-11 

service routines, 4-7 

tables, 4-7 
Software interrupt system, 1-6, 
4-1, 5-17 

enabl i ng, 4-10 
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Software interrupt system (Cont.) 

operational sequence, 4-2 

summary, 4-20 
Source designator, 3*22 
S0UT% JSYS, 3-24, 3-25 

arguments, 3-25 
SPJFN% JSYS, 2-3 
SSAVE% JSYS, 5-11 
Stack 

address, 8-11 

global, 8-11 

pointer, 8-11 

register, 8-11 
Stack instructions, 8-11 

ADJSP, 8-11 

POP, 8-11 

POPJ, 8-11 

PUSH, 8-11 

PUSHJ, 8-11 
Standard file specification, 3 - 3 
Starting a process, 8-17 
Starting inferior process, 5 _ l6 
Status word 

process, 5 - 1 9 
Status-return block, 5"20 
STIW% JSYS, 4-1 6 
Str i ng 

printing a, 2-3 

reading a, 2-10 
Str i ngs 

ASCI I , 2-1, 3-23 

ASCIZ, 2-1, 3-23 

text, 2-1 

transferring, 3~24 
example, 3~26 
Structure 

process, 1-6 
Superior process, 1-7, 5"2 

communicating with inferior, 
5-10 
<SYSTEM>INFO, 7-1. 7-6, 7"7> 7-8, 
7-10, 7-14 

functions and arguments, 7 _ l6 

requests, 7 - l4 
format, 7 _ 15 

responses, 7-17 
<SYSTEM>INFO responses, 7" 17 

Table 

channel (CHNTAB) , k-8 
priority level (LEVTAB) , 4-9 
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software interrupt, 4-7 
Terminal 

input, 2-1 

output, 2-1 
Terminal codes 

deassigning, 4-19 
Terminal interrupts, 4-13 

codes, 4-14 

deferred mode, 4-16 

generating, 4-16 

immediate mode, 4-16 
Terminating inferior process, 

5-17 
Text strings, 2-1 
TMSG macro, 2-4 

example, 2-8 
Transferring bytes, 3"24 
Transferring data, 3-21 
Transferring strings, 3"24 

example, 3~26 
Trap 

illegal instruction, 1-4 
Two-word global byte pointer, 2-2, 
8-11 

Universal device designator, 8-12 
Unmappi ng 

process page, 3 _ 31 

process section, 8- 1 6 

Vector 

entry, 8- 1 8 
Virtual address space, 8-1 
Virtual space, 1-6 

WF0RK% JSYS, 5-4, 5-17, 5-l8 
Writing a byte, 2-9 
Writing a number, 2-6 
Wr i t i ng to a file 
summary, J>-kk 

XBLT instruction, 8-10 
XCT instruction, 8-10 
XGTPW% JSYS, 8-21 
arguments, 8-21 
XGVEC% JSYS, 8-21 
XHLLI instruction, 8-9, 8-10 
XJEN instruction, 8-10 
XJRST instruction, 8-2 
XJRSTF instruction, 8-2, 8-10 
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XMOVEI instruction, 8-9, 8-22 XSFRK* JSYS, 5-17. 8-17 

XPCW instruction, 8-10 arguments, 8-17 

XR!R% JSYS, i»-l8, 8-13 XS l-R* JSYS, W, *»-12, A-20, 8-13 

arguments, A-l8 arguments, U-7 

XRMAP% JSYS, 8-20 XSVEC% JSYS, 8-l8 

arguments, 8-20 arguments, 8-l8 
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